Webhooks & Events
Webhooks let Engium push real-time event notifications to your server — new messages, booking state changes, AI handoffs, and more. Register an HTTPS endpoint and Engium will POST a signed JSON payload on each event.
Prerequisites
- •A publicly accessible HTTPS endpoint (HTTP rejected; TLS required).
- •API Key and Tenant ID for registering the webhook via the API or dashboard.
Implementation
# Register a webhook endpoint
curl -X POST https://api.engium.app/api/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Tenant-ID: YOUR_TENANT_ID" \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourdomain.com/hooks/engium",
"events": [
"conversation.message.received",
"booking.confirmed",
"booking.cancelled"
],
"description": "Production webhook"
}'
# Response includes webhook_secret — save it securely!Request Parameters
| Parameter | Type | Requirement |
|---|---|---|
url | string | Required |
events | string[] | Required |
description | string | Optional |
is_active | boolean | Optional |
urlRequiredYour HTTPS endpoint. Engium POSTs signed JSON here. Must return 2xx within 10 seconds or the delivery is retried.
eventsRequiredEvent types to subscribe to. Use ["*"] to receive all events. Supported: conversation.*, booking.*, payment.*.
descriptionOptionalHuman-readable label shown in the dashboard. Helpful for distinguishing staging vs production endpoints.
is_activeOptionalEnable or disable delivery without deleting the endpoint. Defaults to true.
Always verify signatures
Never process a webhook payload without verifying the X-Engium-Signature header using HMAC-SHA256. Skipping this check exposes you to replay attacks and spoofed events.
Automatic retry policy
Non-2xx responses and timeouts are retried up to 5 times with exponential back-off (1 s → 5 s → 25 s → 125 s → 625 s). Failed deliveries and their payloads are visible in the Engium dashboard under Settings → Webhooks.
Real-time delivery receipts
Subscribe to conversation.message.delivered and conversation.message.read for WhatsApp read receipts. Build live delivery dashboards or trigger follow-up automations the moment a customer sees your message.
Was this helpful?