Documentation

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

EventWhen
message.receivedAn incoming message (text, file, location, contact, poll or reaction)
message.sent_from_phoneA message you sent from the phone itself
message.acceptedWhatsApp accepted an API message for delivery
message.deliveredDelivered to the recipient's device, when WhatsApp reports it
message.readRead by the recipient, when WhatsApp reports it
message.failedSending failed (with an error code)
instance.stateThe connection status changed
group.updatedA group changed (name, settings, participants)
webhook.testSent 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).

Native REST
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      -> 204

WebhooksLive

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.

MethodPath (Admin to change, Viewer to read)Purpose
POST/webhooks{ url, instanceId?, events?[], format?: "native" or "green", authHeader?, description? }
GET/webhooksList
GET/webhooks/eventsValid event names
PATCH / DELETE/webhooks/{id}Update or remove
POST/webhooks/{id}/rotate-secretNew signing secret (shown once)
POST/webhooks/{id}/testSend a signed webhook.test event
GET/webhooks/{id}/deliveriesDelivery log with attempts and status codes

What a delivery looks like

Native format (default)
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.

Node.js (Express)
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 2xx quickly. 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-Delivery id: use it to ignore duplicates.
  • Events can arrive out of order; use createdAt and the message status to order them.
  • Webhook toggles per instance (incoming, outgoing, state) live in the instance settings.