How to receive your customers' WhatsApp messages and social comments by webhook
Each connection gets its own webhook for your customers' WhatsApp messages or social comments through easyCoexistence's Partner API. WhatsApp messages go from Meta straight to that URL, signed with the Tech Provider app's secret rather than one you hold, so a long random secret in the URL path authenticates them. Instagram and Facebook comments and DMs, and TikTok comments, are forwarded as they arrive, signed per account with X-EC-Signature.
Meta's maximum length for the alternate callback URL that sends a number's messages to your endpoint.
How long Meta retries a WhatsApp webhook your endpoint did not accept, with decreasing frequency, which can produce duplicates.
Meta's network; whois route lookups for it list the addresses WhatsApp webhooks come from, which Meta changes periodically.
The largest a WhatsApp webhook payload can be, according to Meta.
Age after which a forwarded event's signed timestamp should be rejected, with the HMAC compared in constant time.
How does each connection get its own destination?
Through one call per resource. A WhatsApp number takes PUT /connections/{id}/webhook with a url and a verify_token, or the same pair as webhook_url and webhook_verify_token on its connect session, so the number routes to you from its first minute. A social account takes PUT /channels/{id}/webhook with a url once it has connected. A url of null on either turns delivery off. The two paths differ in who delivers and how you authenticate:
| WhatsApp number | Instagram, Facebook, TikTok | |
|---|---|---|
| Set with | webhook_url on the session, or PUT /connections/{id}/webhook | PUT /channels/{id}/webhook, after it connects |
| Delivered by | Meta, straight to your URL | easyCoexistence, forwarding each event as it arrives |
| Body | Meta's webhook, unchanged | platform, account_id, external_id and the network's entry |
| Authenticate | A long random secret in the URL path | X-EC-Signature, keyed with the account's secret |
| Retries | Meta's own, for up to 7 days | None: one attempt |
| Copy kept | None | None |
How do you point a number's messages at your endpoint?
Give it an HTTPS URL whose path holds a long random secret, plus a verify token: webhook_verify_token on a connect session, 8 to 200 characters, or verify_token on the PUT. Meta checks the URL at once with a GET carrying hub.mode=subscribe, hub.verify_token and hub.challenge, and your endpoint must answer with the hub.challenge value when the token matches. If that handshake fails, the PUT returns 502 meta_rejected with Meta's own message; on a connect session the number still connects, and the session's last_error says why the URL was not applied.
import express from "express";
import { timingSafeEqual } from "node:crypto";
const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();
function same(a, b) {
const x = Buffer.from(String(a)), y = Buffer.from(String(b));
return x.length === y.length && timingSafeEqual(x, y);
}
// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
return res.sendStatus(403);
}
res.send(req.query["hub.challenge"]);
});
// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
res.sendStatus(200); // answer first: Meta retries for up to 7 days
enqueue(req.body); // deduplicate on each message id before acting
});Why can't you check Meta's signature, and what replaces it?
Meta signs each delivery with X-Hub-Signature-256, an HMAC-SHA256 of the payload keyed with the receiving app's App Secret. For your customers' numbers that app is easyCoexistence's Tech Provider app, and its secret is never shared, so the header cannot be verified on your side. The long random secret in the URL path is the credential instead: compare it in constant time and refuse anything else. As a second layer, allowlist the routes registered to Meta's AS32934 and refresh that list, since Meta changes its IP addresses periodically.
Which WhatsApp webhooks reach your URL?
The fields Meta lets an alternate callback URL carry: messages, for what customers send and the status of what you send; smb_message_echoes, for what the business sends from the WhatsApp Business app; and the one-time import's history and smb_app_state_sync. Meta never sends template webhooks, or account webhooks such as account_update, to an override. They reach easyCoexistence's callback instead, which is why template review is read by polling and a drop reaches you as a status event.
- The destination is set on the WhatsApp Business Account, so two numbers in one account share it: route on value.metadata.
phone_number_id. - Media arrives as an ID; fetch the file from Meta with the customer's token from the credentials call.
- Payloads can reach 3 MB, so raise any body-size limit set below that.
What does a forwarded social event look like?
A POST with Content-Type application/json and an X-EC-Signature header, carrying four keys: platform; account_id, the channel ID the Partner API uses; external_id, the account's ID on the network; and entry. For Instagram and Facebook, entry is Meta's webhook entry unchanged, with changes for comments and mentions and messaging for DMs. For TikTok it holds the comment.update event with its content parsed, and comment_id, video_id and parent_comment_id as strings, so 64-bit IDs are not rounded.
- Instagram accounts are subscribed to comments, messages and mentions; Facebook Pages to feed, messages and mention; TikTok sends comment.update.
- easyCoexistence receives no comment events from YouTube or LinkedIn: their PUT answers 400
not_supported, and their comments are read through each network's API with the credentials. - Forwards carry no X-EC-Event or X-EC-Delivery header, so deduplicate on the network's own IDs, such as a comment ID or a message mid.
{
"platform": "instagram",
"account_id": "<CHANNEL_ID>",
"external_id": "<INSTAGRAM_ACCOUNT_ID>",
"entry": {
"id": "<INSTAGRAM_ACCOUNT_ID>",
"time": 1793440800,
"changes": [
{
"field": "comments",
"value": {
"id": "<COMMENT_ID>",
"from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
"text": "<COMMENT_TEXT>",
"media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
}
}
]
}
}How do you verify X-EC-Signature, step by step?
With the signing_secret that PUT /channels/{id}/webhook returned, shown only once and unique to that account. The header reads t=<unix>,v1=<hex>. Then, for each delivery:
- Read the raw request body as bytes, before any JSON parsing.
- Split the header on commas into t, a Unix time in seconds, and v1, a hex digest.
- Reject the delivery if t is more than 5 minutes away from your clock.
- Compute HMAC-SHA256 over t, a dot and the raw body, keyed with that account's secret, as hex.
- Compare it with v1 in constant time, then answer 2xx and queue the work.
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database
app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
);
if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
return res.sendStatus(401); // missing or stale timestamp
}
let event;
try {
event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
} catch {
return res.sendStatus(400);
}
const secret = secrets.get(event.account_id);
if (!secret || !sig.v1) return res.sendStatus(401);
const expected = createHmac("sha256", secret)
.update(sig.t + ".")
.update(req.body) // the raw bytes, exactly as they arrived
.digest("hex");
if (expected.length !== sig.v1.length ||
!timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
return res.sendStatus(401);
}
res.sendStatus(204); // one attempt and no retries: acknowledge, then work
enqueue(event);
});What happens when no destination is set?
Nothing reaches you, and nothing waits to be sent later. A number with no webhook_url falls back to easyCoexistence's callback, where its messages are dropped without being stored, and it gets no chat history import, which is only requested once a destination exists. A social account without one is not forwarded: its events still reach easyCoexistence's app, but none is held for you. Set each destination before you need the traffic.
What happens to a destination when a connection drops or is removed?
A number keeps its destination on record. When a dropped number reconnects, easyCoexistence sets your URL with Meta again, and the same happens when a suspended number comes back. Removing a social account clears its destination and its secret, so after it reconnects, call PUT /channels/{id}/webhook again and store the new secret. That PUT issues a new secret whenever it is called with a URL, and the old one stops signing at once.
How to set it up
- Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
- Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
- Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
- Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.
Common mistakes
- Checking X-Hub-Signature-256 on your customers' WhatsApp deliveries. Meta computes it with easyCoexistence's app secret, which is never shared, so the check cannot pass; authenticate with the secret in the URL path.
- Verifying X-EC-Signature over parsed JSON. The HMAC covers the raw body byte for byte, and re-serialising it changes the bytes, so verify before parsing.
- Using one secret for every channel. Each social account signs with its own secret, and status events with another, so look the secret up by account_id.
- Doing slow work before answering a forwarded event. It is sent once, waits 8 seconds for your answer and is never retried, so answer 2xx first and process afterwards.
easyCoexistence routes each customer number's messages from Meta straight to your server and forwards Instagram and Facebook comments and DMs, and TikTok comments, to your endpoint as they arrive, signed per account, with no copy kept and every connection monitored 24/7. US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.
easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.
Frequently asked questions
Can I verify Meta's signature on my customers' WhatsApp messages?
No. Meta signs them with the secret of easyCoexistence's Tech Provider app, which is never shared. Authenticate with the long random secret in your URL path, and optionally Meta's IP ranges.
Do YouTube and LinkedIn connections forward comment events?
No. easyCoexistence receives no comment events from either, so PUT /channels/{id}/webhook answers 400 not_supported. Read their comments through each network's API with the channel's credentials.
Are forwarded social events retried if my server is down?
No. Each one is sent once and no copy is kept. WhatsApp deliveries differ, because Meta itself retries them for up to 7 days.
Do messages pass through easyCoexistence?
Not on WhatsApp: Meta delivers a number's messages straight to the webhook you set. Comments and DMs from the social networks are forwarded to your endpoint as they arrive, signed per account, with no copy kept.
Keep reading
Connect your first channel in two minutes.
No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.
- 3 days free
- Cancel any time
- Official APIs only
- Monitored 24/7
Verified on