Webhooks & Event Delivery Architecture
Learn how IndoTium delivers real-time event notifications with HMAC-SHA256 verification, automated retry backoff, and duplicate handling.
Webhook Integration Requirements
HTTPS Only: Webhook endpoints must use valid SSL/TLS certificates.
HMAC Signature Verification: Validate the X-Indotium-Signature header using your endpoint secret.
Fast Acknowledgment: Respond with HTTP 200/202 within 5 seconds; perform heavy processing asynchronously.
Idempotent Handler: Process events using event_id deduplication to handle potential duplicate delivery.
Exponential Backoff: Failed deliveries (HTTP 5xx or timeout) retry up to 8 times over 24 hours.
Sample Webhook Event Payload
Events are delivered via POST with Content-Type: application/json and header X-Indotium-Signature.
{
"event_id": "evt_9f8a7b6c5d4e",
"event_type": "message.delivered",
"created_at": "2026-07-23T10:15:30Z",
"data": {
"message_id": "msg_8849204812",
"channel": "whatsapp",
"recipient": "+15550192834",
"status": "delivered",
"delivered_at": "2026-07-23T10:15:29Z"
}
}HMAC-SHA256 Signature Verification
Use timing-safe string comparison to prevent side-channel timing attacks when checking signatures.
// Node.js example verifying incoming webhook signature
import crypto from "crypto";
function verifyWebhookSignature(payloadBody, signatureHeader, secret) {
const hmac = crypto.createHmac("sha256", secret);
const expectedSignature = "sha256=" + hmac.update(payloadBody).digest("hex");
return crypto.timingSafeEqual(
Buffer.from(signatureHeader),
Buffer.from(expectedSignature)
);
}