Webhooks

Managing Webhooks

Goal: Set up and manage webhooks to send real-time nativeMsg event data to your own systems. Estimated Time: 5–10 minutes

---

What's a webhook?

A webhook is a simple, automated message sent from nativeMsg to your system when a specific event occurs. It’s a way for your tools (like CRMs, analytics, or databases) to receive instant updates — no manual refresh required.

⚙️ When triggered, nativeMsg makes an HTTP POST request to the URL(s) you’ve set in your account.

---

🧭 Where to Manage Webhooks

1. Go to Settings → Webhooks in your nativeMsg dashboard.
2. You’ll see a list of all existing webhooks — inbound and outbound.
3. Each webhook shows:

   • URL endpoint
   • Event type(s)
   • Secret key
   • Edit/Delete options

---

🧱 Types of Webhooks

Type	Description	Example
Inbound	Triggered when data enters nativeMsg (e.g., a message received, user action).	User sends a new message to a bot.
Outbound	Triggered when data leaves nativeMsg (e.g., a message sent, a status change).	Bot sends a message or completes an interaction.

💡 You can add multiple webhooks for different systems or event types — each with its own secret key.

---

🧩 Creating a New Webhook

1. Go to Settings → Webhooks.
2. Click Create New Hook.
3. In the dialog box, fill in the fields:

Field	Description
URL	The endpoint where nativeMsg will POST data. Must include https:// (e.g., https://yourdomain.com/webhook).
Events	Select one or more events you want to trigger this webhook. Examples: message.received, message.sent, user.created.

1. Click Create.

✅ The new webhook is created with a unique secret key for verification and security.

🔒 Keep your secret key private — it’s used to validate that webhook payloads are coming from nativeMsg.

---

✏️ Editing a Webhook

1. Go to Settings → Webhooks.
2. Find the webhook you want to update.
3. Click Edit.
4. Change the URL or Events as needed.
5. Click Update.

✅ The webhook will continue running with the new configuration immediately.

---

🗑️ Deleting a Webhook

1. Go to Settings → Webhooks.
2. Click Delete next to the webhook.
3. Confirm Yes to remove it.

⚠️ Once deleted, events will no longer send to that endpoint.

---

🧠 Pro Tips for Success

Tip	Why It Matters
Always use HTTPS	Ensures secure communication. Plain HTTP is not supported.
Verify your secret key	Authenticate incoming requests to prevent spoofing.
Log incoming payloads	Helps debug or replay webhook data if needed.
Filter events by importance	Avoid unnecessary traffic — subscribe only to what you need.
Test before going live	Use a tool like Webhook.site or Postman to preview data.

---

⚙️ Common Use Cases

Use Case	Description
CRM Integration	Send new lead info or chat interactions to HubSpot, Salesforce, etc.
Analytics Tracking	Log message delivery and engagement events in your BI tool.
Automation Triggers	Launch workflows (e.g., via Zapier or n8n) when users engage with your bot.
Custom Reporting	Store conversation data in your internal database.

💬 Webhooks make nativeMsg part of your larger automation ecosystem.

---

🧩 Example JSON Payload

{
  "event": "message.received",
  "timestamp": "2025-10-08T18:15:00Z",
  "bot_id": "12345",
  "user": {
    "id": "67890",
    "phone": "[phone]"
  },
  "message": {
    "type": "text",
    "content": "Hi, I need help!"
  },
  "signature": "sha256=ab4f123456789cde..."
}

🧠 Use the signature header to verify authenticity using your secret key.

---

✅ Quick Recap

You can:

• Create secure webhook URLs for inbound/outbound events
• Edit or delete existing hooks anytime
• Use webhooks to integrate nativeMsg data with your own systems

🔗 Webhooks are your real-time bridge between nativeMsg and everything else in your tech stack.