WhatsApp Webhooks - Antryk Documentation

Antryk WhatsApp Webhooks allow you to receive real-time WhatsApp events directly in your application. Configure a Callback URL and Signing Secret from your WhatsApp Service dashboard to receive incoming customer messages, message updates, delivery statuses, and other WhatsApp activity through HTTP POST requests. With Antryk WhatsApp Webhooks, you can build:

Automated customer support
WhatsApp chatbots
Real-time notifications
Order and delivery workflows
Customer communication systems
Message synchronization
Delivery tracking
WhatsApp automation
CRM integrations
Custom backend workflows

How WhatsApp Webhooks Work

The Antryk webhook workflow consists of four main steps:

Create or connect a WhatsApp Business service in Antryk.
Configure your application’s webhook endpoint as the Callback URL.
Add a Signing Secret to securely authenticate webhook requests.
Receive and process WhatsApp events in your backend.

When WhatsApp activity occurs, Antryk sends an HTTP POST request to your configured Callback URL.

WhatsApp Activity
       ↓
    Antryk
       ↓
Webhook POST Request
       ↓
Your Callback URL
       ↓
Verify Signature
       ↓
Process Event
       ↓
Return HTTP 2xx Response

Configure WhatsApp Webhook

To configure a webhook, first open the WhatsApp service you want to configure.

Setup Steps

Open the WhatsApp Services section in your Antryk dashboard.
Select the WhatsApp Business service you want to configure.
Open the Overview page.
Click the Webhook button.
Enter your application’s Callback URL.
Configure a Signing Secret.
Review the sample payload.
Click Send Test Event to verify connectivity.
Click Save Configuration.

WhatsApp Webhook Configuration

The WhatsApp webhook configuration drawer contains the settings required to connect your Antryk WhatsApp service to your backend application.

Callback URL

The Callback URL is the public API endpoint where Antryk sends WhatsApp webhook events. For example: https://api.example.com/webhooks/whatsapp Your backend should expose this endpoint and accept HTTP POST requests. The endpoint should be publicly reachable by Antryk and should be capable of receiving JSON request bodies.

Signing Secret

The Signing Secret is a private secret used to verify that webhook requests were sent by Antryk. You should store this secret securely in your backend environment rather than hard-coding it directly into your application source code. For example: WHATSAPP_WEBHOOK_SECRET=your_callback_secret

Security: Never expose your webhook signing secret in frontend code, public repositories, client-side applications, or browser-accessible configuration.

Sample Payload

The webhook configuration drawer provides a sample payload that will be used in sending test event to check connectivity of entered callback URL.

Webhook Configuration Actions

Cancel — Close the webhook configuration drawer without saving changes.
Send Test Event — Send a sample webhook request to your Callback URL.
Save Configuration — Save the Callback URL and Signing Secret.

Building Your Webhook Endpoint

The Callback URL you configure in Antryk must point to a backend route in your application. For example, if you configure: https://api.example.com/webhooks/whatsapp your backend should have a corresponding route: POST /webhooks/whatsapp Antryk will send the WhatsApp event as a JSON request body. Your backend should:

Receive the POST request.
Read the X-Webhook-Signature header.
Retrieve the signing secret from your environment variables.
Calculate the expected signature.
Compare the received signature with the calculated signature.
Reject the request if the signature is invalid.
Process the webhook event.
Return a successful HTTP 2xx response.

Webhook Signature Verification

Every webhook request contains the following HTTP header: X-Webhook-Signature The header contains a SHA-256 HMAC signature generated using the Signing Secret configured for your WhatsApp service. The signature format is: sha256=<signature> Your backend should calculate the expected signature using the raw request payload and your webhook secret.

Signature Verification Flow

Antryk
  ↓
POST webhook request
  ↓
X-Webhook-Signature header
  ↓
Your backend
  ↓
Read webhook secret from environment
  ↓
Generate HMAC SHA-256 signature
  ↓
Compare signatures
  ↓
Valid → Process event
Invalid → Return 401

Important: The webhook secret should be stored as an environment variable or another secure server-side secret store. Do not hard-code production secrets in your source code.

JavaScript Signature Verification

The following example demonstrates how to verify an Antryk webhook request using Node.js and JavaScript.

const crypto = require("crypto");

function verifyWebhookSignature(req) {
  const signature = req.headers["x-webhook-signature"];
  const secret = process.env.WHATSAPP_WEBHOOK_SECRET;

  if (!signature || !secret) {
    return false;
  }

  const expectedSignature =
    "sha256=" +
    crypto
      .createHmac("sha256", secret)
      .update(JSON.stringify(req.body))
      .digest("hex");

  return signature === expectedSignature;
}

A basic Express route can then use the verification function:

const express = require("express");
const crypto = require("crypto");

const app = express();

app.use(express.json());

app.post("/webhooks/whatsapp", (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  const secret = process.env.WHATSAPP_WEBHOOK_SECRET;

  if (!signature || !secret) {
    return res.status(401).send("Invalid signature");
  }

  const expectedSignature =
    "sha256=" +
    crypto
      .createHmac("sha256", secret)
      .update(JSON.stringify(req.body))
      .digest("hex");

  if (signature !== expectedSignature) {
    return res.status(401).send("Invalid signature");
  }

  const event = req.body;

  // Process the verified webhook event.
  console.log("WhatsApp webhook event:", event);

  return res.status(200).json({
    success: true,
  });
});

app.listen(3000, () => {
  console.log("Webhook server listening on port 3000");
});

JavaScript Environment Variable

Store the Signing Secret in your server environment:

WHATSAPP_WEBHOOK_SECRET=your_callback_secret

Do not commit this value to Git or expose it to frontend applications.

Python Signature Verification

The following example demonstrates webhook signature verification using Python.

import os
import hmac
import hashlib
import json

def verify_webhook_signature(request):
    signature = request.headers.get("X-Webhook-Signature")
    secret = os.environ.get("WHATSAPP_WEBHOOK_SECRET")

    if not signature or not secret:
        return False

    payload = json.dumps(request.json, separators=(",", ":"))

    expected_signature = "sha256=" + hmac.new(
        secret.encode("utf-8"),
        payload.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected_signature)

A Flask webhook route can use the verification function like this:

import os
import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/whatsapp", methods=["POST"])
def whatsapp_webhook():
    signature = request.headers.get("X-Webhook-Signature")
    secret = os.environ.get("WHATSAPP_WEBHOOK_SECRET")

    if not signature or not secret:
        return "Invalid signature", 401

    payload = request.get_data()

    expected_signature = "sha256=" + hmac.new(
        secret.encode("utf-8"),
        payload,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected_signature):
        return "Invalid signature", 401

    event = request.get_json()

    # Process the verified webhook event.
    print("WhatsApp webhook event:", event)

    return jsonify({
        "success": True
    }), 200

if __name__ == "__main__":
    app.run(port=3000)

Python Environment Variable

Store your webhook Signing Secret as an environment variable:

WHATSAPP_WEBHOOK_SECRET=your_callback_secret

Do not store the production Signing Secret directly in your Python source code.

Webhook Response Status Codes

Your webhook endpoint should return an HTTP status code indicating whether the request was successfully received and processed.

Successful Responses

Return a 2xx response when the webhook has been accepted. For example: HTTP/1.1 200 OK A successful response tells Antryk that your endpoint received the webhook successfully.

Invalid Signature

If the X-Webhook-Signature does not match the signature calculated using your configured secret, reject the request. For example: HTTP/1.1 401 Unauthorized Example response: Invalid signature

Other Failed Requests

If your endpoint returns an error or cannot be reached, Antryk may retry webhook delivery. Common failure scenarios include:

401 — Invalid webhook signature.
4xx — Invalid or rejected request.
5xx — Server-side processing error.
Timeout — Your endpoint did not respond within the expected time.
Connection failure — Your endpoint could not be reached.

Recommended Webhook Response Flow

A recommended webhook handler follows this pattern:

Receive webhook request
          ↓
Read X-Webhook-Signature
          ↓
Load secret from environment
          ↓
Verify HMAC SHA-256 signature
          ↓
       Valid?
       /    \
     No      Yes
     ↓        ↓
Return 401  Process event
              ↓
            Return HTTP 200

Always verify the webhook signature before trusting or processing the payload.

WhatsApp Webhook Events

When your account receives WhatsApp activity, Antryk forwards a clean, normalized payload to your configured Callback URL using an HTTP POST request. All webhook requests are signed using your configured Signing Secret. Your backend should verify the signature before processing the event.

Event Types Overview

Event	Triggered When
`message`	A customer sends a message such as text, image, video, or document
`message_echo`	Your team sends a message directly from the WhatsApp Business app
`message_edited`	Your team edits a message previously sent from the WhatsApp Business app
`message_revoked`	Your team deletes a message previously sent from the WhatsApp Business app
`message_status`	A message changes delivery state such as sent, delivered, read, or failed

1. `message` — Incoming Customer Message

The message event is fired when a customer sends a message to your WhatsApp Business number.

{
  "event": "message",
  "from": "16315551181",
  "to": "16505551111",
  "messageId": "a1b2c3d4-internal-uuid",
  "waMessageId": "wamid.HBgLMTYzMTU1NTExODEVAgARGBI4...",
  "messageType": "text",
  "body": "Hi, is this order shipped yet?",
  "mediaUrl": null,
  "timestamp": "2026-08-21T09:12:44.000Z",
  "phoneNumberId": "123456123",
  "wabaId": "987654987",
  "contact": {
    "profile": {
      "name": "John Doe"
    },
    "wa_id": "16315551181"
  }
}

Field Notes

from — Customer’s phone number.
to — Your business WhatsApp number.
messageType — Message type such as text, image, audio, video, document, or template.
body — Message text or media caption.
mediaUrl — URL of the resolved media file. This can temporarily be null immediately after receiving the message while media is being resolved.

2. `message_echo` — Message Sent From the App

The message_echo event is fired when someone from your team sends a message directly from the connected WhatsApp Business app rather than through the Antryk API. This keeps your records synchronized with messages manually sent by your staff.

{
  "event": "message_echo",
  "from": "16505551111",
  "to": "16315551181",
  "messageId": "e5f6g7h8-internal-uuid",
  "waMessageId": "wamid.HBgLMTYzMTU1NTExODEVAgARGBI5...",
  "messageType": "text",
  "body": "Yep, shipped this morning!",
  "mediaUrl": null,
  "timestamp": "2026-08-21T09:14:02.000Z",
  "phoneNumberId": "123456123",
  "wabaId": "987654987",
  "contact": null
}

Field Notes

from — Your business WhatsApp number because the message was sent by your team.
to — The customer who received the message.
The remaining fields follow the same structure as an incoming message.
If the message was originally sent through the Antryk Send Message API, a duplicate message_echo event is not generated because messages are deduplicated using waMessageId.

3. `message_edited` — App Message Edited

The message_edited event is fired when your staff edits a message previously sent from the WhatsApp Business app.

{
  "event": "message_edited",
  "from": "16505551111",
  "to": "16315551181",
  "messageId": "e5f6g7h8-internal-uuid",
  "waMessageId": "wamid.HBgLMTYzMTU1NTExODEVAgARGBI5...",
  "messageType": "text",
  "body": "Yep, shipped this morning — tracking number below!",
  "mediaUrl": null,
  "timestamp": "2026-08-21T09:15:10.000Z",
  "phoneNumberId": "123456123",
  "wabaId": "987654987",
  "contact": null
}

Field Notes

waMessageId refers to the original WhatsApp message. Use it to locate and update the corresponding message.
body contains the newly edited content.
For media messages, only the caption can be edited. The attached media file remains unchanged.
mediaUrl therefore remains the same as the original message.
The corresponding message record is updated to edited on the Antryk side.

4. `message_revoked` — App Message Deleted

The message_revoked event is fired when your staff deletes a message previously sent from the WhatsApp Business app.

{
  "event": "message_revoked",
  "from": "16505551111",
  "to": "16315551181",
  "messageId": "e5f6g7h8-internal-uuid",
  "waMessageId": "wamid.HBgLMTYzMTU1NTExODEVAgARGBI5...",
  "messageType": "text",
  "body": "Yep, shipped this morning!",
  "mediaUrl": null,
  "timestamp": "2026-08-21T09:16:30.000Z",
  "phoneNumberId": "123456123",
  "wabaId": "987654987",
  "contact": null
}

Field Notes

waMessageId identifies the message that was deleted.
body contains the last known content before the message was deleted.
If the message was previously edited, the body represents the latest known content.
The corresponding Antryk message record is marked with the status revoked.

5. `message_status` — Delivery Status Change

The message_status event is fired when a message sent through the API or WhatsApp Business app changes its delivery state.

{
  "event": "message_status",
  "status": "delivered",
  "waMessageId": "wamid.HBgLMTYzMTU1NTExODEVAgARGBI5...",
  "messageId": "e5f6g7h8-internal-uuid",
  "customerNumber": "16315551181",
  "timestamp": "2026-08-21T09:14:30.000Z",
  "phoneNumberId": "123456123",
  "wabaId": "987654987"
}

Supported Status Values

sent
delivered
read
failed

A single WhatsApp message can generate multiple status events as it progresses through its delivery lifecycle. For example: sent → delivered → read Each status transition can result in a separate webhook request. Failed messages may include additional error information in the Antryk dashboard and logs.

Common Webhook Fields Reference

Field	Type	Description
`event`	string	Event type such as `message`, `message_echo`, `message_edited`, `message_revoked`, or `message_status`
`status`	string	Delivery state for `message_status`: `sent`, `delivered`, `read`, or `failed`
`from`	string	Sender phone number in E.164 format without `+`
`to`	string	Recipient phone number
`messageId`	string (UUID)	Antryk internal message record ID
`waMessageId`	string	WhatsApp message ID used to correlate messages
`messageType`	string	Message type such as `text`, `image`, `audio`, `video`, `document`, or `template`
`body`	string \| null	Message text or media caption
`mediaUrl`	string \| null	Permanent media URL once the media has been downloaded and resolved
`timestamp`	ISO 8601 string	Time when the event or message was recorded
`phoneNumberId`	string	WhatsApp Business phone number ID
`wabaId`	string	WhatsApp Business Account ID
`contact`	object \| null	Customer WhatsApp profile information for incoming message events

Webhook Retry & Delivery Behavior

Antryk automatically retries webhook delivery when your callback endpoint fails. For reliable webhook processing:

Return a 2xx response quickly.
Keep webhook processing asynchronous where possible.
Avoid long-running operations inside the webhook request.
Make your webhook handler idempotent.
Use waMessageId to identify and deduplicate WhatsApp messages.
Monitor failed webhook requests from the Webhook Audit Logs.

If your endpoint remains unreachable after all retry attempts, the event is recorded in Antryk logs but is not queued indefinitely. Slow responses can be treated as failed deliveries and may result in retry attempts and duplicate webhook requests.

Webhook Security Best Practices

Webhook endpoints should be treated as public-facing API endpoints. Follow these security practices:

Keep your Signing Secret private.
Store the secret in environment variables or a secure secrets manager.
Never expose the secret in frontend code.
Always validate the X-Webhook-Signature header.
Reject requests with invalid signatures.
Use HTTPS for your Callback URL.
Return a 401 response when signature verification fails.
Use waMessageId to prevent duplicate message processing.
Keep webhook processing fast and asynchronous where possible.
Monitor webhook failures through Antryk Webhook Audit Logs.

Before using your webhook in production, test the integration from the Antryk dashboard. If the test fails, inspect your webhook logs for:

HTTP status codes
Request attempts
Target URL
Request payload
Authentication errors
Server errors
Connection failures

Troubleshooting Webhook Issues

Webhook returns 401

A 401 response usually indicates that signature verification failed. Check:

The Signing Secret in your environment matches the Antryk dashboard configuration.
Your backend is reading the X-Webhook-Signature header correctly.
Your HMAC algorithm is SHA-256.
The sha256= prefix is included in the comparison.
The payload used for signature calculation matches the request payload.

Webhook requests are repeated

Repeated webhook requests can occur when Antryk does not receive a successful response from your endpoint. Check:

Your endpoint returns a 2xx response.
Your server responds quickly.
Your endpoint is publicly reachable.
Your webhook handler does not take too long to process events.

Your application should be idempotent and use waMessageId where applicable to prevent duplicate processing.

Webhook endpoint is not receiving requests

Check:

The Callback URL is correct.
The URL uses HTTPS.
Your server is publicly accessible.
Your route accepts POST requests.
Your firewall or reverse proxy allows the request.
Your server is returning a response.
The Send Test Event feature works correctly.

Webhook Audit Logs

Antryk provides Webhook Audit Logs to help developers monitor webhook delivery and troubleshoot integration issues. The audit log provides visibility into webhook delivery attempts made by Antryk.

Webhook Log Information

Column	Description
Date & Time	Time when the webhook delivery attempt occurred
Event ID	Unique identifier for the webhook event
Status	HTTP response status such as 200 or 401
Attempts	Number of delivery attempts
Result	Whether the delivery was successful or failed

Webhook Log Details

Clicking a webhook audit log opens a detail drawer containing additional information about the delivery attempt. Log details can include:

Event information
Delivery status
Attempt information
Target URL
Request payload
Response information
Debugging details

These logs make it easier to diagnose authentication failures, unreachable endpoints, invalid responses, and other webhook integration problems.

​How WhatsApp Webhooks Work

​Configure WhatsApp Webhook

​Setup Steps

​WhatsApp Webhook Configuration

​Callback URL

​Signing Secret

​Sample Payload

​Webhook Configuration Actions

​Building Your Webhook Endpoint

​Webhook Signature Verification

​Signature Verification Flow

​JavaScript Signature Verification

​JavaScript Environment Variable

​Python Signature Verification

​Python Environment Variable

​Webhook Response Status Codes

​Successful Responses

​Invalid Signature

​Other Failed Requests

​Recommended Webhook Response Flow

​WhatsApp Webhook Events

​Event Types Overview

​1. message — Incoming Customer Message

​Field Notes

​2. message_echo — Message Sent From the App

​Field Notes

​3. message_edited — App Message Edited

​Field Notes

​4. message_revoked — App Message Deleted

​Field Notes

​5. message_status — Delivery Status Change

​Supported Status Values

​Common Webhook Fields Reference

​Webhook Retry & Delivery Behavior

​Webhook Security Best Practices

​Troubleshooting Webhook Issues

​Webhook returns 401

​Webhook requests are repeated

​Webhook endpoint is not receiving requests

​Webhook Audit Logs

​Webhook Log Information

​Webhook Log Details

How WhatsApp Webhooks Work

Configure WhatsApp Webhook

Setup Steps

WhatsApp Webhook Configuration

Callback URL

Signing Secret

Sample Payload

Webhook Configuration Actions

Building Your Webhook Endpoint

Webhook Signature Verification

Signature Verification Flow

JavaScript Signature Verification

JavaScript Environment Variable

Python Signature Verification

Python Environment Variable

Webhook Response Status Codes

Successful Responses

Invalid Signature

Other Failed Requests

Recommended Webhook Response Flow

WhatsApp Webhook Events

Event Types Overview

1. `message` — Incoming Customer Message

Field Notes

2. `message_echo` — Message Sent From the App

Field Notes

3. `message_edited` — App Message Edited

Field Notes

4. `message_revoked` — App Message Deleted

Field Notes

5. `message_status` — Delivery Status Change

Supported Status Values

Common Webhook Fields Reference

Webhook Retry & Delivery Behavior

Webhook Security Best Practices

Troubleshooting Webhook Issues

Webhook returns 401

Webhook requests are repeated

Webhook endpoint is not receiving requests

Webhook Audit Logs

Webhook Log Information

Webhook Log Details