Webhooks are critical for managing real-time communication on the WhatsApp Business API. Without active webhooks, your server cannot receive delivery updates (sent, delivered, read status) or capture customer reply payloads.

Setting up webhooks requires configuring an HTTPS endpoint, completing verification handshakes, and parsing incoming JSON payloads. This guide details how developers can configure endpoints, manage webhook states, and process messaging events.

Key Takeaways

  • Webhooks send real-time notification events when users receive or reply to template messages.
  • Verification requires setting a custom Hub Verify Token to authenticate the handshake request.
  • Status payloads allow you to track delivery rates (sent, delivered, read receipts) automatically.
  • Your endpoint must return HTTP status code 200 within 3 seconds to avoid duplicate delivery alerts.

Table of Contents

1. What is a WhatsApp Webhook?

A webhook is a custom HTTP callback endpoint configured to receive data payloads from Meta servers in real-time. Whenever an event occurs (like a user replying to a chat), Meta sends a POST request to your URL.

This event-driven flow is essential to power interactive chatbots. Learn more on our WhatsApp Automation page.

2. The Handshake Verification Protocol

When you link an endpoint URL in Meta Business Manager, Meta transmits a GET request containing verify tokens. Your endpoint must validate these parameters and return the challenge value.

This step secures your URL connection. Manage team inbox configurations on our Shared Team Inbox page.

3. Parsing JSON Message Payloads

When a user sends a text reply, Meta delivers a POST payload containing message details and phone numbers.

Here is an example structure:


{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "10928373729",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16505551111",
              "phone_number_id": "123456789"
            },
            "contacts": [
              {
                "profile": {
                  "name": "John Doe"
                },
                "wa_id": "16505551111"
              }
            ],
            "messages": [
              {
                "from": "16505551111",
                "id": "wamid.HBgLMTY1MDU1NTExMTEVAgIGGBI=",
                "timestamp": "1672531199",
                "text": {
                  "body": "Hello World"
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Review visual editor setups on our WhatsApp Chatbot Builder page. View template layouts on our WhatsApp Template Directory.

4. Tracking Sent, Delivered, & Read Status

Meta sends status update payloads whenever outbound templates change state. Tracking these statuses allows you to measure read rates.

This metrics log campaign results. Review rates on our Pricing Details page.

5. Webhook Security and Best Practices

Secure endpoints by verifying Meta signature headers (X-Hub-Signature-256) using SHA256 hashing. For details on virtual numbers, check our Partnership & Onboarding Portal.

Frequently Asked Questions (FAQs)

Q1: What is a WhatsApp Webhook?

A: An HTTP callback endpoint that receives real-time messaging events and delivery updates from Meta's servers.

Q2: Why must my webhook return status 200 within 3 seconds?

A: If your endpoint delays, Meta flags a delivery failure and retries sending the payload, causing duplicate updates.

Q3: What are webhook verify tokens?

A: Custom strings you configure inside the Meta developer dashboard to authenticate verification requests.

Q4: Can we use webhooks to sync messaging data to HubSpot?

A: Yes. Incoming webhook payloads can be parsed to update contact logs inside HubSpot programmatically.

Q5: What are the main message statuses sent to webhooks?

A: Meta sends status updates for 'sent', 'delivered', 'read', 'failed', and 'deleted' events.

Q6: Do we need coding skills to verify webhooks?

A: Yes. Handling handshakes and parsing JSON payloads requires backend development skills (e.g. Node.js, Python).

Q7: What is the open rate for messages received via webhooks?

A: Customer reply messages have a 100% open rate since they originate from the user, triggering immediate chatbot sequences.

Q8: How do we prevent webhook connection drops?

A: Host endpoints on scalable cloud servers (e.g. AWS, Heroku) and monitor error logs to prevent crashes.

Q9: Can we receive media attachments via webhooks?

A: Yes. The payload contains file IDs for images or PDFs, which you download using Meta's media endpoints.

Q10: What is the verified green tick benefit for webhooks?

A: The tick is verified at the profile level, protecting delivery reputations even when processing thousands of webhook actions.

Q11: Can we test webhooks in sandbox environments?

A: Yes. You can register test endpoints under Meta's developer sandbox to test payload parsing before deploying live numbers.

Q12: Can we register landline numbers to trigger webhooks?

A: Yes. Landline number activations trigger the same webhook configurations once verified on the API.

Q13: What happens if a webhook remains offline?

A: Meta queues undelivered events for up to 24 hours. Once your endpoint is online, queued payloads are delivered.

Q14: Are virtual numbers allowed to receive webhook events?

A: Yes. All registered API numbers deliver messaging payloads to configured webhook endpoints.

Q15: Can we run automated NPS surveys using webhooks?

A: Yes. Tapping feedback buttons in surveys triggers webhook events, allowing you to record patient ratings automatically.

Next Steps

Configuring secure, low-latency webhooks is essential to build responsive chatbots and track message delivery rates.

Ready to register webhook endpoints? Connect with our developer support team to start parsing payloads today.