Skip to main content
Outbound webhooks are HTTP calls Keebai makes to your server when something happens in your account — an inbound WhatsApp message, a status change, a template update, a new connection. They’re the flip side of the API: instead of you polling, Keebai pushes the event to you.
Not to be confused with the inbound webhooks Meta sends to Keebai. Those are configured by Keebai in the Meta dashboard when you connect a channel via Embedded Signup; you don’t touch them.

​
Use cases

Sync messages to your CRM

Receive every whatsapp.message.received and store it in your system along with the conversation, contact, and content.

Track delivery / read

Subscribe to whatsapp.message.delivered / .read / .failed to report delivery rates in your dashboard.

React to templates

Receive whatsapp.template.status_updated when Meta approves or rejects a template, and notify your marketing team.

Automated provisioning

Listen for whatsapp.channel.connected to trigger your onboarding flow the moment a channel is ready.

​
How it works

1

Register an HTTPS URL

Via CLI (keebai webhooks new) or via API (POST /v1/webhooks). Specify the events you care about and optionally extra headers.
2

Keebai returns a secret

Once. You use it to verify that each delivery actually came from us (HMAC-SHA256 signature). It cannot be retrieved later — store it in your secret manager.
3

When an event happens, we deliver it

POST call to your URL with the standard JSON envelope and signature headers. If your endpoint responds 2xx, we mark the delivery as successful. If it responds 5xx / timeout / 408 / 429, we retry with exponential backoff (5 attempts, up to ~3h).
4

After 50 consecutive failures, we auto-disable

To avoid hammering an endpoint that’s been down for a long time. You receive an email and the subscription is left with is_active: false and disabled_reason: 'excessive_failures'. Reactivate via PATCH.

​
Envelope

Every event shares the same outer shape. The difference is the data field, discriminated by type. 
{
  "id": "evt_01HXYZABC...",
  "type": "whatsapp.message.received",
  "occurred_at": "2026-04-27T12:34:56.789Z",
  "company_id": "comp_xxx",
  "channel_id": "ch_xxx",
  "data": {
    "phone_number_id": "1234567890",
    "from": "+56912345678",
    "to": "+56987654321",
    "message_id": "wamid.HBgL...",
    "type": "text",
    "text": { "body": "Hola!" },
    "timestamp": "1714214096"
  }
}
FieldTypeDescription
idstringUnique event ID. Stable: if we retry the delivery, the same ID arrives. Use it to deduplicate.
typeenumDiscriminator from the catalog. See events.
occurred_atISO-8601Event timestamp (UTC).
company_idstringYour Keebai company ID.
channel_idstring | nullChannel associated with the event, if applicable.
dataobjectEvent-specific payload. Shape varies by type.

​
Delivery headers

Every POST to your endpoint includes:
HeaderExampleUsage
X-Keebai-Signaturet=1714214100,v1=8f2c...HMAC-SHA256 signature over ${t}.${rawBody}. See security.
X-Keebai-Event-Idevt_01HXYZ...Same as body.id. Handy for dedup without parsing the body.
X-Keebai-Event-Typewhatsapp.message.receivedDiscriminator.
X-Keebai-Delivery-Iddlv_...Delivery attempt ID. Changes between retries of the same event.
X-Keebai-Timestamp1714214100Unix seconds when the signature was generated. Same value as t= in X-Keebai-Signature.
User-AgentKeebai-Webhooks/1.0
Content-Typeapplication/json
+custom headersIf you configured headers when creating the subscription, they’re included too.

​
Guarantees and limitations

At-least-once delivery

If your endpoint times out or returns 5xx, we retry. Your endpoint must be idempotent: dedup by event_id.

No ordering guarantee

Events from the same channel can arrive out of chronological order (especially with retries). Use occurred_at to sort.

10s timeout

If your endpoint doesn’t respond within 10 seconds, we count a timeout and retry. Process fast and return 2xx; if you need heavy work, push it to your own queue.

HTTPS required

We don’t accept http:// URLs. Use a valid certificate (Let’s Encrypt works).

​
Next steps

Event catalog

Full list of type values and the data shape for each one.

Signature verification

How to validate X-Keebai-Signature with HMAC-SHA256 in Node, Python, and PHP.

Manage via CLI

Quickstart with keebai webhooks new/list/test/rotate/delete.

Manage via API

REST endpoints /v1/webhooks to create, list, rotate, delete, and test.