# 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`. |

4. 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](https://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

```json
{
  "event": "message.received",
  "timestamp": "2025-10-08T18:15:00Z",
  "bot_id": "12345",
  "user": {
    "id": "67890",
    "phone": "+15555550123"
  },
  "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.*