> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Learn how to receive Notifique events in your system in real time.

<Tip>
  A webhook is your server's **doorbell**: when something happens in Notifique (message sent, delivered, customer reply…), we ring it with a JSON POST to your URL.
</Tip>

## What is a webhook?

It's an **HTTPS URL** on your system that receives automatic alerts from Notifique. Instead of polling the API asking "was it delivered?", you **wait for the alert to arrive**.

Think of it like a push notification, but for your backend.

## What is it for?

With webhooks you can:

* **Know right away** when a message was sent, delivered, read, or failed
* **Automate** orders, CRM, billing, and bots without checking the dashboard
* **Process** messages customers send you (WhatsApp, Telegram, SMS)
* **Monitor** instance connection (QR, connected, disconnected)
* **Track** short-link clicks and Forms events

## When to use?

| Situation                                           | Use a webhook? |
| --------------------------------------------------- | -------------- |
| Need to react **right away** when something changes | **Yes**        |
| Want to automate (bot, ERP, your system)            | **Yes**        |
| Only check the dashboard occasionally               | Not required   |

## How to set up

### 1. Prepare your endpoint

Create an **HTTPS** route that accepts **POST** JSON and responds **2xx** quickly.

Example: `https://yoursite.com/webhooks/notifique`

If processing is heavy, **queue** on your side and return 200 immediately. Like answering the doorbell and handling the visit later.

### 2. Register in the dashboard

Open **Developer → Webhooks**, create a webhook, and select the [events](#events-by-channel) that matter to you.

You can also register via the API with scopes `webhooks:manage` and `webhooks:read`. Need a key? See [API Keys](/guides/api-key/index).

```http theme={null}
POST https://api.notifique.dev/v1/webhooks
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "name": "My webhook",
  "url": "https://api.yoursite.com/receive",
  "events": ["message.sent", "message.delivered", "sms.sent"],
  "instanceIds": []
}
```

**Store the secret** from the response. You use it to validate each POST.

### 3. Validate the signature

Each POST includes `X-Notifique-Signature` and `X-Notifique-Timestamp`. Compute HMAC-SHA256 of the secret with `{timestamp}.{raw body}` and reject timestamps outside **5 minutes**.

Details in the [Headers and signature](#headers-and-signature) section below.

### 4. Handle retries

If your endpoint fails, we retry at **5 min, 30 min, and 2 h**. Respond **2xx** quickly.

## Sandbox vs production

* **Sandbox** (`sk_test_...`): same event names; payload includes `sandbox: true`
* **Production** (`sk_live_...`): real events from live traffic

Simulate events in **Developer → Sandbox inbox**. More in [Sandbox mode](/guides/sandbox/index).

## Payload format

All requests are **POST** with `Content-Type: application/json`. The body follows this structure:

```json theme={null}
{
  "event": "message.sent",
  "workspaceId": "clxx...",
  "instanceId": "clxx...",
  "messageId": "clxx...",
  "timestamp": "2025-02-09T12:00:00.000Z",
  "data": { ... }
}
```

| Field           | Type                | Description                                                                                                           |
| --------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **event**       | string              | Event name (e.g. `message.sent`, `sms.delivered`).                                                                    |
| **workspaceId** | string              | Workspace ID.                                                                                                         |
| **instanceId**  | string              | WhatsApp instance ID (empty for SMS, email, and push).                                                                |
| **messageId**   | string \| undefined | Message ID in Notifique (when applicable); for **`short_link.clicked`** it is the **clickEventId** (click record ID). |
| **timestamp**   | string              | ISO 8601; use for anti-replay (recommended window: 5 min).                                                            |
| **data**        | object              | Event-specific data (see each channel page below).                                                                    |

## Headers and signature

| Header                    | Description                                        |
| ------------------------- | -------------------------------------------------- |
| **Content-Type**          | `application/json`                                 |
| **X-Webhook-Event**       | Event name.                                        |
| **X-Notifique-Timestamp** | Timestamp in seconds (Unix) used in the signature. |
| **X-Notifique-Signature** | Signature: `t={timestamp},v1={hash}`.              |
| **X-Workspace-Id**        | Workspace ID.                                      |

* **HMAC calculation:** `hash = HMAC-SHA256(secret, timestamp + "." + body)` (body = raw POST body).
* **Anti-replay:** Reject requests with a timestamp outside a window (e.g. 5 minutes).

## Inbound messages

To process what the **customer sent** (WhatsApp, Telegram, SMS):

1. Subscribe to the event on the webhook
2. Configure inbound in **Settings → Received messages**

The webhook notifies you with a summary. To **download media** (audio, image, document) on WhatsApp, use `inboundId` via the API. Full guide: [Inbound messages and replies](/guides/webhooks/mensagens-recebidas-e-respostas).

## Best practices

1. **HTTPS always** on the registered URL
2. **Respond 2xx quickly** and process in the background
3. **Validate the signature** on every POST
4. **Subscribe only to events** your integration consumes

More details: [Security and reliability](/guides/conceitos/seguranca-e-confiabilidade).

## Events by channel

Each channel has its own events. Select only what you need:

<CardGroup cols={2}>
  <Card title="WhatsApp" icon="whatsapp" href="/en/whatsapp-api/como-funciona/eventos-do-webhooks">
    Send, delivery, inbound, and instance
  </Card>

  <Card title="SMS" icon="comment-sms" href="/en/sms-api/como-funciona/eventos-do-webhooks">
    Send, DLR, MO, and replies
  </Card>

  <Card title="Telegram" icon="paper-plane" href="/en/telegram-api/como-funciona/eventos-do-webhooks">
    Send, inbound, and instance
  </Card>

  <Card title="Instagram" icon="instagram" href="/en/instagram-api/como-funciona/eventos-do-webhooks">
    Send, comments, and inbound
  </Card>

  <Card title="Email" icon="envelope" href="/en/emails-api/como-funciona/eventos-do-webhooks">
    Send, open, click, and bounce
  </Card>

  <Card title="Push" icon="bell" href="/en/push-api/como-funciona/eventos-do-webhooks">
    Send, delivery, and click
  </Card>

  <Card title="RCS" icon="mobile-screen" href="/en/rcs-api/como-funciona/eventos-do-webhooks">
    Send, delivery, and failure
  </Card>

  <Card title="Voice" icon="phone" href="/en/voice-api/como-funciona/eventos-do-webhooks">
    Calls and recordings
  </Card>

  <Card title="Forms" icon="clipboard-list" href="/en/marketing-addons-api/como-funciona/eventos-do-webhooks">
    Subscribe, confirm, and unsubscribe
  </Card>

  <Card title="Short links" icon="link" href="/en/short-links-api/como-funciona/eventos-do-webhooks">
    Clicks and conversions
  </Card>

  <Card title="Phone numbers" icon="hashtag" href="/en/phone-numbers-api/como-funciona/eventos-do-webhooks">
    Contracted number lifecycle
  </Card>

  <Card title="Automations" icon="bolt" href="/automations-api/como-funciona/eventos-do-webhooks">
    Enable, pause, and run lifecycle
  </Card>

  <Card title="Templates (Meta)" icon="file-lines" href="/en/template-api/como-funciona/eventos-do-webhooks">
    Approval, rejection, and category
  </Card>
</CardGroup>

<Note>
  Workspace reputation event (`trust.score_changed`): see [Trust Factor](/guides/workspaces/trust-factor#webhook-trustscore_changed).
</Note>

***

## Next steps

* [Start here](/guides/introducao/comece-aqui): send your first message
* [API Keys](/guides/api-key/index): credentials to register webhooks via API