Webhook & API Support - FAQs
FAQs for using Chakra Chat APIs and inbound webhooks.
Covers inbound event webhooks (pass-through and Chakra-format), HMAC signing, message history recovery, Coexistence, and send-side idempotency.
1. General Webhook Behavior
Does the webhook support retry, queuing or batching? What's the required response deadline and body for a successful acknowledgement?
There is no retry or queuing policy on either Pass through or Chakra webhooks. A successful acknowledgement is an HTTP 200 with no response body required, and it must be returned in under 200 ms. Reference: Inbound Events Webhook docs
Can webhook events be batched, duplicated, or delivered out of order? Are duplicate deliveries byte-identical, and is every delivery independently HMAC-signed?
Batching is not supported, and events can arrive out of order. Reference: Inbound Events Webhook — HMAC Validation section
What webhook body-size, batch-size, concurrency, and delivery-throughput limits apply?
No limits are published. Fair use is expected.
2. Recovering Missed Events
If a webhook is missed, what endpoint can enumerate the missing inbound messages, delivery statuses, and Business App echoes?
There is no dedicated "missed events" endpoint. Missed inbound messages can be recovered through the chat history APIs, filterable by plugin ID and WhatsApp phone number ID. An equivalent lookup for delivery statuses or Business App echoes — along with retention windows or consistency-delay figures — isn't covered in published documentation and should be treated as not currently available pending internal confirmation. Reference: List chats | List chat messages | List previous messages for a phone number
3. Payloads & Event Identification
Where can I find complete redacted current payloads for message, status, message_echo, and smb_message_echo, including a failed status with all error fields?
Sample payloads are published in the Inbound Events Webhook reference. Reference: Inbound Events Webhook — sample payloads
For status, message_echo, and smb_message_echo events, which fields identify the plugin, WABA, and receiving business phone number when one account has multiple numbers?
For pass-through/Meta-format events, the receiving number appears in value.metadata.phone_number_id / display_phone_number, and the WABA ID appears in entry[].id.
- Sample inbound text message event: apidocs.chakrahq.com/doc-919167#sample-inbound-text-message-event
- Inbound event object structure: apidocs.chakrahq.com/doc-919167#inbound-event-object-structure
Reference: Inbound Events Webhook
Which Business App messages produce smb_message_echo, and are there any unsupported types or companion devices?
All Business App text and media messages generate smb_message_echo events. Unsupported message types are:
- Polls
- Ephemeral messages
- Deleted messages
4. Outbound Message Controls
Does our account include pass-through webhooks, custom webhooks, HMAC, and Coexistence echoes?
Every Chakra Chat account supports pass-through webhooks, custom webhooks, HMAC, and Coexistence echoes.
5. HMAC Secret & Rotation
Do we supply the HMAC secret, or does Chakra generate it?
You supply it, set under Admin > Team > Secrets. Reference: Inbound Events Webhook — HMAC Validation
Regenerating the team HMAC secret immediately invalidates the previous one. What cutover procedure prevents webhook loss during rotation, and can old/new signatures overlap temporarily? The rotation mechanism is documented (secret set under Admin > Team > Secrets, delivered via the X-Chakra-Signature-256 header), but no cutover procedure or signature-overlap window is supported. Reference: Inbound Events Webhook — HMAC Validation
Can the same callback and secret receive pass-through messages, statuses, message_echo, and smb_message_echo events?
All Chakra-format and pass-through events (message, status, message_echo, smb_message_echo) share a single callback URL and a single HMAC secret. The Meta pass-through feed uses a separate URL, and HMAC signing for that feed specifically is not documented. Reference: Inbound Events Webhook
6. Callback URL Configuration
Where do we configure the webhook callback URL — dashboard or API? In the Chakra dashboard: WhatsApp Setup page → "More" tab → "Pass-through webhook url" field (Meta-format) and "Chakra webhook url" field (Chakra-format).
It can also be set programmatically via the plugin config API: apidocs.chakrahq.com/api-33925592
Reference: Inbound Events Webhook
Is the callback team-wide, WABA/plugin-wide, or specific to each phone number?
Per plugin. Each WhatsApp Setup plugin instance has its own pass-through and Chakra webhook URL fields — there is no team-level webhook. Within a given plugin, WABA/phone-number-specific webhooks can be configured. Reference: Inbound Events Webhook
7. API Idempotency
Does any send endpoint support a client idempotency key or duplicate-suppression mechanism? After a timeout, how do we conclusively determine whether a message was accepted?
No idempotency key parameter is supported on the send endpoints. A successful send returns a WhatsApp message ID (wamid) synchronously in the response body. The documented path after a timeout is to query chat/message history and match on that wamid — there is no idempotency-key or duplicate-suppression mechanism on the send call itself. Reference: Send WhatsApp session message | List chat messages
8. Coexistence Disconnection
What provider-side release and escalation SLA applies when disconnecting Coexistence, including residual partner/billing associations?
The customer provides their own billing details to Meta directly, so no residual billing issue is possible. Reference: Disconnect WABA Account | Deregister a WhatsApp business phone number