Glossary · 30 terms
Webhooks & events
Webhooks are how the WhatsApp Business Platform tells your system that something happened. These terms cover subscriptions and verification, payload anatomy, message and status events, retries, ordering and deduplication.
Foundation· 6
Start here — the concepts everything else builds on.
- Messages WebhookThe messages webhook delivers every message a WhatsApp user sends to your business number — text, media, button taps, locations, reactions — as a JSON POST.Read definition
- WebhookAn HTTP POST that the WhatsApp Business Platform sends to your server the moment something happens — an inbound message, a delivery status, a template update.Read definition
- Webhook PayloadThe JSON body of every WhatsApp webhook: an envelope of object, entry and changes wrapping the field-specific value your code actually reads.Read definition
- Webhook TestingExercising a webhook handler before go-live with dashboard test payloads, a local tunnel, signed replays of captured events and Meta's test number.Read definition
- Webhook Verification RequestThe GET Meta sends to a callback URL with hub.mode, hub.verify_token and hub.challenge; the endpoint must echo the challenge with a 200 to be accepted.Read definition
- Webhooks vs PollingWebhooks push each WhatsApp event to your server as it happens; polling asks an API again and again. Cloud API inbound messages are push-only.Read definition
Practitioner· 21
What you need once you are running it day to day.
- Account Update WebhookThe account_update webhook tells your app when a WhatsApp Business Account changes state: a violation, restriction, ban, partner link or pricing tier.Read definition
- Business Capability Update WebhookThe business_capability_update webhook reports a new messaging limit or phone-number allowance for a business, so senders can resize campaigns at once.Read definition
- Phone Number Quality WebhookThe phone_number_quality_update webhook reports status changes for one business number, such as onboarding and the upgrade to 1,000 messages per second.Read definition
- Statuses WebhookStatus webhooks report what happened to each message you sent — sent, delivered, read, played or failed — keyed by its wamid, with pricing and error details.Read definition
- Subscribed Apps Endpointsubscribed_appsThe /{WABA_ID}/subscribed_apps endpoint connects a WhatsApp Business Account to your Meta app, so that account's webhooks start flowing to your callback URL.Read definition
- Template Category Update WebhookThe template_category_update webhook warns you before Meta recategorises an approved template, such as utility to marketing, and confirms once it has.Read definition
- Template Quality WebhookThe message_template_quality_update webhook reports when a template's quality score moves between GREEN, YELLOW and RED — the early warning before a pause.Read definition
- Template Status WebhookThe message_template_status_update webhook reports each change in a template's state — approved, rejected, paused, disabled, archived — with the reason.Read definition
- User Preferences WebhookThe user_preferences webhook tells your server when a WhatsApp user stops or resumes marketing messages from your business, so consent records stay in sync.Read definition
- Webhook AcknowledgementAnswering each WhatsApp webhook with HTTP 200 once it is verified and safely stored, then processing it asynchronously so slow work never looks like a failure.Read definition
- Webhook Contacts ObjectThe contacts array in WhatsApp webhooks that identifies who an event is about: profile name, wa_id and, with usernames, a business-scoped user_id.Read definition
- Webhook Conversation Object (Legacy)The legacy conversation block (id, origin.type, expiration_timestamp) in WhatsApp status webhooks, which the pricing object replaced under per-message pricing.Read definition
- Webhook DeduplicationDetecting and discarding repeated WhatsApp webhook deliveries, keyed on the wamid plus status or the event's identity, before any side effect runs.Read definition
- Webhook EndpointThe public HTTPS URL, and the server behind it, that receives WhatsApp webhooks: a CA-signed certificate, fast 200s and headroom for spikes and 3 MB payloads.Read definition
- Webhook Error ObjectsThe errors arrays WhatsApp webhooks carry on failed statuses, unsupported inbound messages and system-level problems, each with a code, title and details.Read definition
- Webhook Event OrderingWhy WhatsApp webhooks arrive out of order — a read before its delivered, a reply before its status — and how to sequence events by timestamp and status rank.Read definition
- Webhook FieldsThe named WhatsApp Business Account webhook fields — messages, message_template_status_update, account_update and more — that decide which events you receive.Read definition
- Webhook Pricing ObjectThe pricing block on WhatsApp status webhooks — pricing_model, type, category and billable — that shows how each message you send is charged.Read definition
- Webhook Referral ObjectAd details attached to an inbound WhatsApp message sent from a Click-to-WhatsApp ad: source URL, ad ID, headline, media and the ctwa_clid click ID.Read definition
- Webhook Retry PolicyHow Meta re-sends a WhatsApp webhook that does not get an HTTP 200: again and again, less often each time, for up to seven days before dropping it.Read definition
- Webhook SubscriptionThe app-level setup that tells Meta where to send WhatsApp webhooks: a callback URL, a verify token and the WABA fields you want to receive.Read definition
Expert· 3
Edge cases, internals and the details that matter at scale.
- Message Echoes WebhookThe smb_message_echoes webhook copies messages a business sends from the WhatsApp Business app on a coexistence number to the API, so CRM threads stay whole.Read definition
- Webhook Fan-OutDistributing one incoming WhatsApp webhook stream to several internal consumers — inbox, CRM, chatbot, analytics — through a broker or relay you control.Read definition
- Webhook OverrideAn alternate callback URL set on a WhatsApp Business Account or phone number, so its message events reach a different endpoint from the app default.Read definition
Put these terms to work.
Go live on the official WhatsApp Business API in 2 hours with a 7-day free trial — no card required.
7-day free trial Enterprise-grade reliability Live in 2 hours Built for Indian businesses