Skip to content
man glossary/webhook-endpoint

glossary define webhook-endpoint

Name

Webhook Endpoint

The 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.

Synopsis

Webhook URL, Webhook receiver, Callback endpoint, Webhook server

Section

Webhooks & events

Level

practitioner

▍

Reviewed

Follow a webhook down through your stack

6 / 6

PayloadPOST /webhooks/whatsapp · status batch

Enters at the top, travels down through 6 layers

A batch of status updates leaves Meta and descends through each layer of a well-built endpoint. Step through to see what every layer must get right for the event to arrive safely.

Hop 6 of 6: the payload is in layer 6, Workers and consumers. Inbox, CRM, bots and analytics process the event; failures are retried internally and parked in a dead-letter queue.

Description

What is a webhook endpoint?

A webhook endpoint is the receiving side of every WhatsApp event: a publicly reachable HTTPS URL plus the infrastructure and code behind it. Meta calls it with a GET to verify it when you register it, then with a POST for every batch of events — inbound messages, delivery statuses, template and account updates. It has to be reachable around the clock, because Meta offers no API to fetch webhooks you missed: anything the endpoint fails to receive is retried for up to seven days and then gone.

Meta's requirements are short but strict. The URL must use HTTPS with a valid certificate that is correctly installed — self-signed certificates are not supported — so serve the full chain from a public certificate authority and renew it automatically. Payloads can be up to 3 MB and carry up to 1,000 updates, so every proxy in front of the handler must accept bodies that large. Meta's webhook servers come from IP ranges that change periodically, which is why Meta recommends mutual TLS over IP allowlists if you want to restrict who can connect: once mTLS is enabled on your WhatsApp Business Account webhook subscription, Meta presents a client certificate and your server checks that its common name is client.webhooks.fbclientcerts.com. That certificate is now signed by a Meta-owned certificate authority, which replaced the DigiCert-signed one that expired on 15 April 2026, so a trust store still pinned to the old chain rejects Meta's connections.

Hosting choices follow from that: a container or VM fleet behind a load balancer, a serverless function behind an API gateway, or a managed ingestion layer that writes straight to a queue. Partners that serve many customers can also point individual WhatsApp Business Accounts or phone numbers at different endpoints with a webhook override (an alternate callback URL of up to 200 characters), for fields such as messages; template and account webhooks always go to the app's default URL.

The endpoint is where and how events are received; the webhook acknowledgement is the per-request contract — return 200 once the event is stored. A well-hosted endpoint with a slow handler still fails, and a perfect handler on an expired certificate receives nothing.

Key takeaways

  • A webhook endpoint is the public HTTPS URL, and the servers behind it, that receives every WhatsApp event for your app.
  • It needs a valid CA-signed certificate served with its full chain; Meta does not support self-signed certificates.
  • Accept request bodies of at least 3 MB: webhook payloads can reach that size and batch up to 1,000 updates.
  • Meta changes its webhook IP addresses periodically and suggests mutual TLS rather than IP allowlists.
  • There is no API to fetch missed webhooks: failed deliveries are retried for up to seven days, then dropped.

Mechanics

How does a webhook endpoint work?

  1. step 1 — Choose a stable public URL

    Use a dedicated hostname and path, such as https://hooks.example.in/webhooks/whatsapp, that does not change between deploys and is not tied to a developer's tunnel.

  2. step 2 — Install a CA-signed certificate

    Serve the full certificate chain over Transport Layer Security 1.2 or later and automate renewal. Self-signed certificates are not supported, and an incomplete chain fails the same way.

  3. step 3 — Answer verification and check signatures

    Handle the webhook verification request — a GET with hub.mode, hub.verify_token and hub.challenge — and validate X-Hub-Signature-256 on every POST before trusting it.

  4. step 4 — Size it for bursts

    A broadcast produces a wave of statuses — up to three per message. Accept 3 MB bodies, run at least two instances, and hand events to a durable queue so ingestion never waits on processing.

  5. step 5 — Register it and subscribe

    Save the callback URL and verify token in your app's WhatsApp webhook settings, subscribe to the fields you need, and add per-WABA or per-number overrides only where you need separate endpoints.

  6. step 6 — Monitor it from outside

    Probe the URL from an external location, alert on certificate expiry, on non-200 responses and on a drop in event rate — silence is the failure you will not otherwise see.

Properties

A webhook endpoint: key facts and limits

Transport
HTTPS, valid CA-signed certificate
Self-signed certificates
Not supported
Maximum payload
3 MB, up to 1,000 updates
Missed events
Retried up to 7 days; no history API
mTLS client certificate
CN client.webhooks.fbclientcerts.com
mTLS trust anchor
Meta-owned outbound CA (the DigiCert-signed cert expired 15 April 2026)
Override URL length
Up to 200 characters

Usage

A webhook endpoint in code

upstream webhook_handlers {
  server 10.0.1.11:8080;
  server 10.0.1.12:8080;          # at least two instances
}
 
server {
  listen 443 ssl;
  server_name hooks.example.in;
 
  ssl_certificate     /etc/letsencrypt/live/hooks.example.in/fullchain.pem;  # full chain
  ssl_certificate_key /etc/letsencrypt/live/hooks.example.in/privkey.pem;
  ssl_protocols       TLSv1.2 TLSv1.3;
 
  client_max_body_size 4m;        # Meta payloads reach 3 MB; nginx defaults to 1 MB
 
  location = /webhooks/whatsapp {
    proxy_pass http://webhook_handlers;
    proxy_read_timeout 10s;
  }
}

Full certificate chain, a body limit above 3 MB and more than one handler behind the proxy.

Why it matters

Why does a webhook endpoint matter?

The endpoint is the single doorway for everything your customers say on WhatsApp. If it is unreachable, mis-certified or saturated, inbound messages stop reaching agents and bots, delivery statuses stop updating campaigns and template pauses go unnoticed — and nothing on Meta's side will page you. Treating it as production infrastructure, with its own monitoring, capacity plan and certificate renewal, is what keeps a WhatsApp integration two-way.

Caveats

Common mistakes with a webhook endpoint

  • An expired or incomplete certificate

    A missed renewal, or serving cert.pem instead of the full chain, makes Meta's TLS handshake fail and every event queue up as a retry. Automate renewal and alert well before expiry.

  • Proxies rejecting large bodies

    Many proxies and frameworks default to 1 MB. A large batch then gets 413, Meta retries it, and it fails again. Raise every limit in the path above 3 MB.

  • Bot protection in front of the URL

    CAPTCHAs, JavaScript challenges, basic auth or geo-blocking on the webhook path block Meta's servers. Exempt the path and authenticate with the signature or mTLS instead.

  • Development URLs in production

    A tunnel URL from a laptop works in a demo and disappears when the laptop sleeps. Register only stable, monitored hostnames for live numbers.

  • Stale IP allowlists

    Meta's webhook IP ranges change periodically, so a hard-coded allowlist eventually drops real traffic. Prefer mTLS plus signature checks.

Example

Example: An Ahmedabad D2C brand's first big sale

An Ahmedabad skincare brand ran its webhook handler on a single small VM. During its first big sale the status wave from a 200,000-message campaign pushed response times past several seconds, Meta started retrying, and the inbox lagged for an hour. It moved the endpoint behind a load balancer with two instances, raised the proxy body limit to 4 MB, put a queue between the handler and its CRM sync, and added an external probe plus a certificate-expiry alert. The next sale's status wave was absorbed by the queue while the handler kept answering in milliseconds.

Notes

Best practices for a webhook endpoint

  • Keep the webhook path on its own hostname so firewall, rate-limit and WAF rules can treat it separately.
  • Make webhook testing routine: run the three pre-launch checks in CI against staging after every infrastructure change.
  • Separate ingestion from processing: the endpoint stores and acknowledges, and webhook fan-out to inbox, CRM and bots happens behind a queue.
  • Graph the event rate per field; a sudden flat line is an outage even when nothing errors.

Questions

Webhook Endpoint FAQs

Can I use a self-signed certificate?
No. Meta requires a valid certificate that is correctly installed, and self-signed certificates are not supported. Free CA-signed certificates with automated renewal work well, as long as you serve the full chain.
Does the endpoint need a fixed IP address?
No. Meta connects to your hostname. What changes is Meta's own IP ranges, which is why Meta suggests mTLS rather than IP allowlists if you need to restrict access.
Can a serverless function be my WhatsApp webhook endpoint?
Yes, if it answers quickly and reliably. Keep the function to verify, store and acknowledge, watch cold-start latency, raise the gateway's body limit above 3 MB and push events to a queue for processing.
Can different phone numbers use different endpoints?
Yes, for some fields. Webhook overrides set an alternate URL per WhatsApp Business Account or per phone number for fields such as messages, while template and account fields always go to the app's default URL.

See InfiQ pricing

Put Webhook Endpoint to work

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms