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.
What is the latency for webhook events when subscribed to webhooks?
The historical measured latency between a Meta event hitting Chakra Webhook and then an attempt being made to send the event to the is about 10-50 ms.
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
Which fields/events are subscribed is our WABA subscribed to?
The following events are subscribed to and are available via the pass through webhook
The account_alerts webhook notifies you of changes to a business phone number’s messaging limit, business profile, and Official Business Account status. | |
The account_review_update webhook notifies you when a WhatsApp Business Account has been reviewed against our policy guidelines. | |
The account_update webhook notifies of changes to a WhatsApp Business Account’s partner-led business verification submission, its authentication-international rate eligibility, or primary business location, when it is shared with a Solution Partner, policy or terms violations, offboarding, reconnection, or when it is deleted. | |
The automatic_events webhook notifies you when we detect a purchase or lead event in a chat thread between you and a WhatsApp user who has messaged you via your Click to WhatsApp ad, if you have opted-in to Automatic Events reporting. | |
The business_capability_update webhook notifies you of WhatsApp Business Account or business portfolio capability changes (messaging limits, phone number limits, etc.). | |
The calls webhook notifies you of call events for user-initiated calls and business-initiated calls, such as when a call is connected or terminated. | |
The history webhook is used to synchronize the WhatsApp Business app chat history of a business customer onboarded by a solution provider. | |
The message_template_components_update webhook notifies you of changes to a template’s components. | |
The message_template_quality_update webhook notifies you of changes to a template’s quality score. | |
The message_template_status_update webhook notifies you of changes to the status of an existing template. | |
The messages webhook describes messages sent from a WhatsApp user to a business and the status of messages sent by a business to a WhatsApp user. | |
The partner_solutions webhook describes changes to the status of a Multi-Partner Solution. | |
The payment_configuration_update webhook notifies you of changes to payment configurations for Payments API India and Payments API Brazil. | |
The phone_number_name_update webhook notifies you of business phone number display name verification outcomes. | |
The phone_number_quality_update webhook notifies you of changes to a business phone number’s throughput level. | |
The security webhook notifies you of changes to a business phone number’s security settings. | |
The smb_app_state_sync webhook is used for synchronizing contacts of WhatsApp Business app users who have been onboarded via a solution provider. | |
The smb_message_echoes webhook notifies you of messages sent via the WhatsApp Business app or a companion (“linked”) device by a business customer who has been onboarded to Cloud API via a solution provider. | |
The template_category_update webhook notifies you of changes to template’s category. | |
The user_preferences webhook notifies you of changes to a WhatsApp user’s marketing message preferences. |
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