Webhooks

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.

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 that matter to you. You can also register via the API with scopes webhooks:manage and webhooks:read. Need a key? See API Keys.

POST https://api.notifique.dev/v1/webhooks
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "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 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.

Payload format

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

{
  "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):

Subscribe to the event on the webhook
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.

Best practices

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

More details: Security and reliability.

Events by channel

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

Send, delivery, inbound, and instance

SMS

Send, DLR, MO, and replies

Send, inbound, and instance

Instagram

Send, comments, and inbound

Email

Send, open, click, and bounce

Push

Send, delivery, and click

RCS

Send, delivery, and failure

Voice

Calls and recordings

Forms

Subscribe, confirm, and unsubscribe

Short links

Clicks and conversions

Phone numbers

Contracted number lifecycle

Automations

Enable, pause, and run lifecycle

Templates (Meta)

Approval, rejection, and category

Workspace reputation event (trust.score_changed): see Trust Factor.

Next steps

Start here: send your first message
API Keys: credentials to register webhooks via API

Simple guides

Learn more

Workspaces

AI and no-code

BYOK

What is a webhook?

What is it for?

When to use?

How to set up

1. Prepare your endpoint

2. Register in the dashboard

3. Validate the signature

4. Handle retries

Sandbox vs production

Payload format

Headers and signature

Inbound messages

Best practices

Events by channel

WhatsApp

SMS

Telegram

Instagram

Email

Push

RCS

Voice

Forms

Short links

Phone numbers

Automations

Templates (Meta)

Next steps

​What is a webhook?

​What is it for?

​When to use?

​How to set up

​1. Prepare your endpoint

​2. Register in the dashboard

​3. Validate the signature

​4. Handle retries

​Sandbox vs production

​Payload format

​Headers and signature

​Inbound messages

​Best practices

​Events by channel

WhatsApp

SMS

Telegram

Instagram

Email

Push

RCS

Voice

Forms

Short links

Phone numbers

Automations

Templates (Meta)

​Next steps

What is a webhook?

What is it for?

When to use?

How to set up

1. Prepare your endpoint

2. Register in the dashboard

3. Validate the signature

4. Handle retries

Sandbox vs production

Payload format

Headers and signature

Inbound messages

Best practices

Events by channel

Next steps