Receiving & webhooks
The notification queue, signed webhooks, payloads and verifying signatures.
Every event (an incoming message, a delivery receipt, a connection change) goes to two places: a polling queue you read when you want, and any signed webhooks you registered. Use whichever suits you; you can use both.
EventsLive
| Event | When |
|---|---|
| message.received | An incoming message (text, file, location, contact, poll or reaction) |
| message.sent_from_phone | A message you sent from the phone itself |
| message.accepted | WhatsApp accepted an API message for delivery |
| message.delivered | Delivered to the recipient's device, when WhatsApp reports it |
| message.read | Read by the recipient, when WhatsApp reports it |
| message.failed | Sending failed (with an error code) |
| instance.state | The connection status changed |
| group.updated | A group changed (name, settings, participants) |
| webhook.test | Sent by the Test button so you can check your endpoint |
Polling queueLive
Servers that cannot expose a public URL can poll: take the next notification, process it, then delete it. Unread notifications are kept for 24 hours (up to 10,000 per instance).
GET https://api.sendjade.com/api/v1/instances/{id}/notifications/next
-> { "data": { "receiptId": 12, "event": "message.received", "envelope": { ... } } } (or { "data": null })
DELETE https://api.sendjade.com/api/v1/instances/{id}/notifications/12 -> 204WebhooksLive
Register a public HTTPS endpoint (Admin role). Private and loopback addresses are refused. You can limit a webhook to one instance and to certain events. The signing secret (whsec_...) is shown once, when you create the webhook or rotate its secret.
| Method | Path (Admin to change, Viewer to read) | Purpose |
|---|---|---|
| POST | /webhooks | { url, instanceId?, events?[], format?: "native" or "green", authHeader?, description? } |
| GET | /webhooks | List |
| GET | /webhooks/events | Valid event names |
| PATCH / DELETE | /webhooks/{id} | Update or remove |
| POST | /webhooks/{id}/rotate-secret | New signing secret (shown once) |
| POST | /webhooks/{id}/test | Send a signed webhook.test event |
| GET | /webhooks/{id}/deliveries | Delivery log with attempts and status codes |
What a delivery looks like
POST https://your-server.example.com/webhooks/sendjade
Content-Type: application/json
X-Sendjade-Event: message.delivered
X-Sendjade-Delivery: 7c1e... (the delivery id: unique per event)
X-Sendjade-Signature: t=1795000000,v1=3b9f... (see below)
Authorization: <your authHeader, if you set one>
{
"id": "7c1e...",
"event": "message.delivered",
"createdAt": "2026-11-18T10:15:00.000Z",
"instance": { "id": "...", "idInstance": "7083920886", "wid": "2348012345678" },
"data": {
"id": "9f2c...", "waMessageId": "3EB0A1B2C3D4E5F6A7", "direction": "OUT",
"chatId": "2348098765432@s.whatsapp.net", "type": "document", "fileName": "Invoice-1042.pdf",
"externalRef": "INV-1042", "status": "DELIVERED", "timestamp": 1795000000
}
}Verify the signature
The header is X-Sendjade-Signature: t=<unix seconds>,v1=<hex>. Compute HMAC-SHA256(secret, "<t>.<raw body>") over the exact raw request body, compare it to v1 in constant time, and reject timestamps older than about 5 minutes to stop replays.
import crypto from 'node:crypto';
import express from 'express';
const app = express();
// Verify against the EXACT raw body, so read it raw (not parsed).
app.post('/webhooks/sendjade', express.raw({ type: 'application/json' }), (req, res) => {
const header = req.get('X-Sendjade-Signature') || ''; // t=<unix>,v1=<hex>
const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));
const t = Number(parts.t);
const raw = req.body.toString('utf8');
const fresh = t && Math.abs(Date.now() / 1000 - t) <= 300; // reject replays older than ~5 minutes
const expected = crypto.createHmac('sha256', process.env.SENDJADE_WEBHOOK_SECRET).update(t + '.' + raw).digest('hex');
const ok = fresh && parts.v1 && parts.v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
if (!ok) return res.sendStatus(401);
res.sendStatus(200); // answer fast, work afterwards
const body = JSON.parse(raw); // { id, event, createdAt, instance, data }
// De-duplicate on req.get('X-Sendjade-Delivery'): retries re-send the same delivery id.
});Delivery, retries and de-duplication
- Answer with any
2xxquickly. Anything else is retried 6 times with exponential backoff (starting at 30 seconds and doubling) and recorded in the delivery log. - Retries re-send the same body and the same
X-Sendjade-Deliveryid: use it to ignore duplicates. - Events can arrive out of order; use
createdAtand the messagestatusto order them. - Webhook toggles per instance (incoming, outgoing, state) live in the instance settings.