ChatSyncs Help Center
Sign in
Browse guides

Webhooks

WhatsApp webhooks: setting up an endpoint, subscribing, reading incoming messages and delivery statuses, handling them reliably, and what each error code means.

8 pages

  1. Webhooks — What and WhyWhat WhatsApp webhooks are and why you need them — Meta's server sends JSON to your endpoint for incoming messages, delivery receipts, and template status changes.
  2. Webhook Endpoint SetupHow to set up a webhook endpoint for the WhatsApp Cloud API and pass the Meta verification handshake — Meta sends a GET challenge your server must echo back.
  3. Subscribe WABA WebhookHow to subscribe to webhook fields on a WhatsApp Business Account so Meta starts delivering inbound messages to your endpoint.
  4. Parsing Inbound PayloadsHow to parse the JSON payload Meta sends to your webhook for each inbound message type — text, image, video, audio, document, and interactive button/list replies.
  5. Status WebhooksThe four delivery status events Meta sends to your webhook after you send a message — sent, delivered, read, and failed — what each means and how to parse them.
  6. Full Round TripThe complete lifecycle of one WhatsApp bot interaction — inbound webhook, reply logic, outbound API call, and status events confirming delivery.
  7. Webhook ReliabilityThree rules for reliable WhatsApp webhook handling — respond 200 immediately, deduplicate deliveries by message ID, and don't assume messages arrive in order.
  8. Error Handling & CodesHow to handle WhatsApp Cloud API errors and what the common codes mean — 190 (token expired), 131030 (test recipient missing), 131047 (24-hour window closed), 131049 (per-user marketing limit), 131026 (undeliverable), 131031 (account locked), 131037 (display name not approved), 131042 (payment method), 131056 (pair rate limit), 132000/132001/132012/132015 (template errors), 368, 130429.