Productivity

WhatsApp Webhooks: Filter by Chat, Test, and Secure with Headers

Three settings turn a firehose of WhatsApp events into something you can ship: a chat filter, a test call, and sealed custom headers. Real requests and responses.

Daniel Roth8 min read

WhatsApp Webhooks: Filter by Chat, Test, and Secure with Headers
On this page

The first version of most WhatsApp webhook integrations has the same three problems. The endpoint receives every message from every chat, including a Status update from someone you met once. Nobody knows whether it works until a real customer writes in. And anyone who finds the URL can POST fake events to it.

Blueticks added a setting for each problem on 2026-11-18: a per-webhook chat filter, a test endpoint, and custom headers. This guide uses all three against the real API, with the exact request and response shapes. Everything below is curl and Node, so you can paste it into a terminal.

You need an API key and a public HTTPS URL. If you have not registered a webhook yet, the webhooks guide covers the basics, and the event reference lists every payload.

How do you create a WhatsApp webhook that only receives one chat?

Pass chat_ids when you create the webhook. The webhook then receives events only from those chats.

Bash
curl -X POST https://api.blueticks.co/v1/webhooks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.your-server.com/wa-events",
    "events": ["new_message_received_webhook"],
    "description": "Support group only",
    "chat_ids": ["120363025246125486@g.us"],
    "include_status_and_channels": false
  }'

The 201 response is the full webhook object:

JSON
{
  "success": true,
  "data": {
    "id": "6a380a8258bece30b485036e",
    "url": "https://api.your-server.com/wa-events",
    "events": ["new_message_received_webhook"],
    "description": "Support group only",
    "status": "enabled",
    "chat_ids": ["120363025246125486@g.us"],
    "include_status_and_channels": false,
    "header_names": [],
    "createdAt": "2026-11-18T19:04:00.000Z",
    "signingSecret": "whsec_..."
  }
}

Keep the id and the signingSecret. You need both later.

The rules for the two filter fields:

  • chat_ids takes up to 100 ids. Omit it, or send [], to receive every chat.
  • To change the list later, PATCH the webhook with a new chat_ids. Sending [] clears the filter.
  • include_status_and_channels defaults to true. Set it to false and the webhook skips WhatsApp Status (status@broadcast) and Channel (@newsletter) events.
  • The two combine. An event has to pass both checks to be delivered.
  • Events that do not belong to a chat, such as session.connected or campaign.completed, are never filtered out.

Webhooks created before these fields existed read back as chat_ids: [] and include_status_and_channels: true, so nothing changes for them.

Why does my phone-number chat id never match?

This one costs people an afternoon. A person's chat can be identified two ways: the phone-number form (15550100123@c.us) or WhatsApp's newer @lid form. The filter treats @c.us and @s.whatsapp.net as the same person, but it does not translate a phone id into an @lid id. If a contact's messages arrive as @lid and your filter lists only the @c.us id, the filter drops them.

The fix is boring: if a contact can show up either way, put both ids in chat_ids. Group ids (@g.us) have one form and do not have this problem.

To find the ids in the first place, list your chats with GET /v1/chats and copy the chatId of each one you want.

How do you test a WhatsApp webhook without waiting for a real message?

Call the test endpoint. It sends one signed sample event to the webhook's URL and reports what your server did.

Bash
curl -X POST https://api.blueticks.co/v1/webhooks/6a380a8258bece30b485036e/test \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "new_message_received_webhook"}'

The body is optional. event has to be one the webhook subscribes to, and it defaults to the first one. Name an event the webhook is not subscribed to and you get a 400 that lists the ones it is.

If your endpoint answers with any 2xx:

JSON
{
  "success": true,
  "data": {
    "ok": true,
    "status": 204,
    "latency_ms": 142,
    "event": "new_message_received_webhook"
  }
}

If it does not, the call still returns 200. Read data.ok, not the HTTP status. Here the endpoint never answered inside the 10-second limit:

JSON
{
  "success": true,
  "data": {
    "ok": false,
    "latency_ms": 10003,
    "event": "new_message_received_webhook",
    "hint": "Timed out after 10s. The endpoint must answer within 10 seconds; acknowledge first, process later."
  }
}

Fields with no value are left out rather than sent as null, which is why there is no status here. The hint field covers the usual suspects: a 401 or 403 from your server, a 404 or 405 on the wrong path, a 5xx, a redirect (these are not followed, so register the final URL), a DNS or TLS failure, and a URL that resolves to a private address.

What does the test request look like on your server?

Your server receives the normal envelope with two tells. The id starts with evt_test_, and there is a top-level "test": true:

JSON
{
  "id": "evt_test_4f9c1b7a2e6d8035a1c4b7e2",
  "type": "new_message_received_webhook",
  "created_at": "2026-11-18T19:12:41.502Z",
  "test": true,
  "data": {
    "id": {
      "_serialized": "false_15550100123@c.us_TESTMSG0000000000000001",
      "fromMe": false,
      "remote": "15550100123@c.us",
      "id": "TESTMSG0000000000000001"
    },
    "chatId": "15550100123@c.us",
    "author": { "_serialized": "15550100123@c.us" },
    "to": { "_serialized": "15550100999@c.us" },
    "fromMe": false,
    "body": "Hello from a Blueticks webhook test",
    "type": "chat",
    "hasMedia": false,
    "timestamp": 1795029161,
    "caption": null,
    "filename": null,
    "notifyName": "Test Sender"
  }
}

For message.*, session.* and campaign.* events, data is a one-line note instead of a message. Either way it is sample data, so branch on test and skip any side effects:

JavaScript
if (event.test) return res.sendStatus(204); // verified and acknowledged, nothing to process

A few properties make the test safe to run against a live webhook:

  • It goes straight to your URL. It is not queued, not retried, and not recorded as a delivery.
  • It never counts toward auto-disable, so a failing test cannot switch off a webhook that is working.
  • It ignores chat_ids. The sample is always from a made-up chat, and the test still reaches you.
  • It carries your custom headers and the signature headers, so you are testing the same checks a real delivery hits.
  • It is rate limited: one test per webhook every 5 seconds, 20 per hour per account. Past that you get a 429.

How do you secure a WhatsApp webhook endpoint?

Layer two checks. The first is the signing secret, which proves the body came from the sender you registered and was not changed on the way. The second is a header you choose, which lets you reject anything that does not carry it before you do any work.

Every webhook you create now returns a signingSecret, and each delivery carries Blueticks-Webhook-Timestamp and Blueticks-Webhook-Signature headers. The signature is v1= plus the hex HMAC-SHA256 of {timestamp}.{raw body}. Custom headers sit next to it. (A webhook created before signing shipped has no secret and delivers unsigned, so the receiver below would reject it. Delete and recreate that webhook to get one.)

Set them with PATCH:

Bash
curl -X PATCH https://api.blueticks.co/v1/webhooks/6a380a8258bece30b485036e \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"headers": {"Authorization": "Bearer 7f3c9a1e5b2d4c68", "X-Source": "wa-prod"}}'

Generate your own token for that value. Something like openssl rand -hex 24 is plenty.

The rules:

  • A name must be Authorization or start with X-. Anything else is rejected with a 400, as are X-Blueticks-*, X-Forwarded-* and X-Real-IP.
  • Up to 10 headers. Each value is 1 to 1024 printable ASCII characters, no line breaks. A bad header returns a 400 that names it.
  • The values are stored encrypted and never returned. The webhook object shows only the names:
JSON
"header_names": ["Authorization", "X-Source"]
  • PATCH replaces the whole set, so send every header you want to keep. "headers": null removes them all.
  • Headers the platform sets itself win, and you cannot set them: Content-Type, the signature headers and Blueticks-* names are not allowed names, so the API answers 400 instead of accepting them. Nobody can use this field to spoof a signature.

A receiver that checks both, in Node:

JavaScript
import crypto from 'node:crypto';
import express from 'express';
 
const app = express();
const SECRET = process.env.WEBHOOK_SECRET;      // whsec_..., from the webhook object
const TOKEN = `Bearer ${process.env.WEBHOOK_TOKEN}`; // the Authorization value you set
const TOLERANCE_SECONDS = 300;
 
const safeEqual = (a, b) => {
  const x = Buffer.from(a);
  const y = Buffer.from(b);
  return x.length === y.length && crypto.timingSafeEqual(x, y);
};
 
// express.raw keeps the exact bytes. Do not use express.json() on this route.
app.post('/wa-events', express.raw({ type: 'application/json' }), (req, res) => {
  // 1. Cheap check first: your own header.
  if (!safeEqual(req.header('Authorization') ?? '', TOKEN)) return res.sendStatus(401);
 
  // 2. Signature over timestamp + raw body, with replay protection.
  const ts = req.header('Blueticks-Webhook-Timestamp') ?? '';
  const sig = req.header('Blueticks-Webhook-Signature') ?? '';
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > TOLERANCE_SECONDS) {
    return res.sendStatus(400);
  }
  const expected =
    'v1=' +
    crypto
      .createHmac('sha256', SECRET)
      .update(Buffer.concat([Buffer.from(`${ts}.`, 'utf8'), req.body]))
      .digest('hex');
  if (!safeEqual(expected, sig)) return res.sendStatus(401);
 
  const event = JSON.parse(req.body.toString('utf8'));
  if (event.test) return res.sendStatus(204);
 
  // Acknowledge now, process after. The limit is 10 seconds per attempt.
  res.sendStatus(204);
  handle(event);
});
 
function handle(event) {
  console.log(event.type, event.data.chatId);
}
 
app.listen(3000);

Run the server, point the webhook at it, and call the test endpoint again. A good run returns "ok": true. Change the token on the server side and call it a third time: the test comes back with ok: false, status: 401 and a hint that your endpoint rejected the request with a 401 and to check the signature verification against your signingSecret. That failure is your proof the lock works.

A custom header is a shared secret, so it proves the sender knew your token and nothing more. Keep the signature check on. It is the one that catches a tampered body.

What should the final setup look like?

A webhook for one support group, locked down, is three calls you have already seen:

  1. POST /v1/webhooks with events, chat_ids and include_status_and_channels: false.
  2. PATCH /v1/webhooks/{id} with headers.
  3. POST /v1/webhooks/{id}/test until ok is true.

From there the usual rules apply. Failed deliveries are retried for up to 8 attempts over about 21 hours, the same event can arrive twice (dedupe on the event id), and an endpoint that fails continuously for 3 days, with at least 10 failed attempts, is switched off. The reliability section of the docs has the numbers.

Frequently asked questions

Does the chat filter apply to the test endpoint? No. The test posts a sample from a made-up chat straight to your URL, so it ignores chat_ids. It also ignores include_status_and_channels.

Can I read back a header value I set? No. Values are sealed at rest and the API returns only header_names. If you lose a token, PATCH a new one.

Can I set Content-Type or the signature header myself? No. Those names are rejected with a 400 when you create or update the webhook, so a custom header can never override or forge the signature, the content type or the webhook id.

Which header names can I use? Authorization, or any name starting with X-, except X-Blueticks-* and X-Forwarded-*. You can set up to 10.

How many chats can one webhook filter on? Up to 100 chat ids per webhook. For more, create a second webhook, or leave the filter empty and route in your own code.

Does a failed test disable my webhook? No. A test is not a delivery and never counts toward the failure rule that auto-disables an endpoint.

Share this article

The Dispatch, every week.

One sharp WhatsApp growth tactic in your inbox each week. Joined by 238,000+ founders, marketers and support leads.

Free forever. No spam, unsubscribe in one click.

Also on TikTok: @blueticksagents