Your events, your route.

Three modes, and the trade each one makes

Most vendors pick one of these and call it a philosophy. It is a two-field setting, so we ship all three and let you decide per connection.

Forwarding is the interesting one. You get webhooks on your own server and you keep the inbox, because we relay from our side rather than routing Meta away from us. A router that never sees message content cannot offer that; it is not a roadmap item for them, it is a rebuild.

On a direct connection payloads are never written to disk, not even briefly in a raw table that is pruned later. A table that is pruned is still a table that held the content.

Override precedence

Meta accepts an alternate callback URL at two levels, and resolves them in a fixed order. Cosend configures whichever level your mode needs and reads the setting back afterwards rather than assuming it took:

1. Business phone number override — the narrowest, and what direct delivery uses.
2. WABA-level override — every number on the account.
3. The app-level callback — ours, which is the default.

Two things about overrides are worth knowing before you plan around them. Template and account-level webhooks do not support overrides at all — those always arrive on the app-level callback, which means on a direct connection they still come to us and we relay them. And Meta verifies your endpoint with a challenge request before it will accept the configuration, so the URL has to be live at the moment you set it.

Event catalogue

One envelope for every event, of every type. data.object is the full resource in the same shape a GET returns, so there is one parser rather than one per event, and previous_attributes appears on updates listing only what changed.

Messages

Conversations

Contacts

The number itself

Automation and usage

Signing — two schemes, and which one you get

Which header arrives depends on who sent the delivery, so both are here and each is labelled. Verify before you trust the body, and compare in constant time in both cases — a plain string comparison leaks timing.

Cosend events — default and forwarding modes

v1 is an HMAC-SHA256 of "{t}.{raw body}", hex. Parse t, reject anything more than five minutes old, recompute over the raw body. During a secret rotation both secrets sign and both v1= values are present.

Cosend-Signature: t=1755687852,v1=5257a869e7bcfd6d6…

This is Stripe's scheme, deliberately. Every developer has already implemented it, every language has a snippet for it, and the timestamped payload resists replay. Inventing a signing scheme here would be a novelty with no upside.

Meta's payloads — direct delivery

Meta signs with X-Hub-Signature-256, prefixed sha256=. Capture the raw bytes before any JSON middleware touches them: re-serialising loses Meta's exact escaping and the HMAC will never match.

// the raw request body, not the parsed object
const expected = crypto
  .createHmac("sha256", APP_SECRET)
  .update(rawBody)
  .digest("hex");

const got = header.slice("sha256=".length);
return got.length === expected.length &&
  crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));

Delivery and retries

At-least-once, unordered, idempotent by event id. Every webhook system is this one; the ones that pretend otherwise create bugs in their customers' code.

Meta's own retry schedule is a different thing, and its documentation contradicts itself. The WhatsApp webhooks page says delivery is retried with decreasing frequency for up to seven days; the general Graph webhooks page says a few times over the following 36 hours. On direct delivery that is the schedule your endpoint is on, so plan durability against the shorter figure and duplicate suppression against the longer one. Meta also batches updates into one request when it can, and says batching is not guaranteed.