WABA API Webhooks
WABA API Webhooks deliver real-time notifications when WhatsApp Business Platform events occur in your TimelinesAI workspace. They use the same subscription mechanism, delivery model, and retry policy as the regular PublicAPI Webhooks — the difference is the set of WABA-specific event types and payload shapes described below.How it works
1
Register a webhook
Use
POST /webhooks to subscribe to a WABA event type and provide your endpoint URL2
An event occurs
A WABA message arrives, a WABA chat changes state, a template is reviewed by Meta, or an account status changes
3
You receive a POST request
TimelinesAI sends the event payload to your endpoint in real-time
4
Acknowledge receipt
Your server responds with a 2xx status within 5 seconds
Available events
WABA message events
WABA chat events
WABA account events
WABA template events
Failed messages —
waba:message:failed carries a structured failure_reason object with code, title, and details. It is present only on the failed event and omitted for received, delivered, and read.Payload shapes — WABA message webhook events bundle the account, chat, and message objects together in a single payload. Each event group has its own schema — see the individual event pages for the exact fields.
Endpoint requirements
Your webhook endpoint must:Be publicly accessible (no localhost in production)
Use HTTPS
Respond with a 2xx status within 5 seconds
Accept POST requests with JSON body
Managing webhooks
WABA webhook subscriptions are managed via the same Public API endpoints as regular webhooks:
See the Webhooks guide for setup instructions and code examples.
Next steps
WABA API
Explore all WABA API endpoints
PublicAPI Webhooks
Regular WhatsApp webhook events