Overview
DLR webhooks let your application receive message status changes without polling GET /v1/messages/:message_id.
Bar9 sends a webhook when an SMS message moves through delivery states such as sent, delivered, or failed. Each request is signed with your webhook signing secret so your server can verify that the event came from Bar9 and was not modified in transit.
Configure delivery in the dashboard
- Open the dashboard and go to Webhooks.
- Enter your HTTPS endpoint URL. Local and private network hosts are rejected.
- Save the configuration and copy the signing secret shown once into a server-side secret store. Existing secrets are only shown as a preview.
- If you lose the secret, rotate it from the same dashboard page; the previous secret stops validating new deliveries immediately.
Configuring a webhook requires approved production access.
Event request
Bar9 sends a POST request with JSON body and these headers:
| Header | Notes |
|---|---|
X-Bar9-Event-ID |
Unique event id. Store it to make processing idempotent. |
X-Bar9-Event-Type |
Event name, for example message.delivered. |
X-Bar9-Timestamp |
Unix timestamp used in the signature. |
X-Bar9-Signature |
HMAC-SHA256 signature with a v1= prefix. |
Content-Type |
application/json. |
Example payload:
{
"id": "evt_...",
"type": "message.delivered",
"created_at": 1778407200,
"data": {
"id": "msg_...",
"to": "+213****0000",
"sender": "BAR9",
"type": "message",
"status": "delivered",
"provider_message_id": "abc123",
"segments": 1,
"cost_credits": 5,
"created_at": 1778407000,
"queued_at": 1778407000,
"sent_at": 1778407100,
"delivered_at": 1778407200,
"failed_at": null,
"failure_reason": null
}
}
Verify signatures
Build the signed payload as:
{X-Bar9-Timestamp}.{X-Bar9-Event-ID}.{raw request body}
Compute HMAC-SHA256 with your webhook signing secret and compare it to X-Bar9-Signature after removing the v1= prefix. Use a constant-time comparison and reject timestamps outside a short window such as five minutes.
import crypto from 'node:crypto';
function verifyBar9Webhook({ secret, timestamp, eventId, rawBody, signature }) {
const value = signature.startsWith('v1=') ? signature.slice(3) : signature;
const signedPayload = `${timestamp}.${eventId}.${rawBody}`;
const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex');
const expectedBytes = Buffer.from(expected, 'hex');
const valueBytes = Buffer.from(value, 'hex');
if (expectedBytes.length !== valueBytes.length) return false;
return crypto.timingSafeEqual(expectedBytes, valueBytes);
}
Handle retries and duplicates
Return a 2xx status only after accepting the event. Store X-Bar9-Event-ID and ignore duplicates. Process webhooks asynchronously when possible, keep the endpoint fast, verify the signature before parsing business fields, and do not trust the event until verification succeeds.