whatsapp-cloud-client

A typed WhatsApp Cloud API client for Node. Webhook signature verification first, in constant time and fail-closed.

Install

npm i whatsapp-cloud-client

It ships TypeScript sources, not compiled JavaScript, so it needs a TypeScript-aware runtime or bundler — Bun, tsx, Vite, Next, esbuild. That is a deliberate choice for now and not an oversight: a compiled build is worth adding, and it is not worth pretending to have.

Example

import { verifyMetaSignature, parseMetaWebhook } from "whatsapp-cloud-client/webhook";

// In your webhook handler. The RAW body — not the parsed one: re-serialising changes the bytes and
// the signature stops matching, which is the single most common way this check silently never passes.
export async function handler(rawBody: string, headers: Headers) {
  if (!verifyMetaSignature(rawBody, headers.get("x-hub-signature-256"), process.env.META_APP_SECRET ?? "")) {
    return new Response("bad signature", { status: 401 });
  }

  const { inbound, statuses } = parseMetaWebhook(JSON.parse(rawBody));

  for (const message of inbound) {
    // message.from is E.164 without the '+', message.body is the text,
    // message.media is present when it carried an image, document, audio or video.
    console.log(message.from, message.body);
  }
  for (const status of statuses) {
    console.log(status.providerMessageId, status.status); // sent | delivered | read | failed
  }
  return new Response("ok");
}

What it does

• Verifies the webhook signature over the raw body, in constant time, and answers false when the header or the secret is missing — never a pass by omission.
• Parses the webhook tolerantly: an unexpected shape yields empty sections instead of throwing, so one malformed message never costs you the rest of the batch.
• Sends text, templates, media and interactive messages, and uploads media to the Cloud API.
• Classifies Meta's errors into what is worth retrying and what is not — including the 400s that are really rate limiting in disguise, and the revoked token that no retry will ever fix.
• Does not: manage your tenants, store anything, or decide when to send. It talks to Meta.

---

Why it exists

Most of the code you write against the WhatsApp Cloud API is not sending messages — it is the part around it. Verifying that a webhook is really from Meta. Deciding whether a failure is worth retrying. Discovering that a media download is two calls and that the second one is not JSON. Finding out that a button parameter must be the link suffix, because Meta concatenates it onto the base it stored — and that it does not fail on send: the message is accepted, the row says delivered, and the link only breaks when the customer taps it.

This package is that part, extracted from a system where it runs against live customer conversations.

Design notes

The signature check is fail-closed and takes the raw body. Every other design leaks: comparing with === leaks timing, and re-serialising the parsed body changes the bytes so the check silently never passes — which looks exactly like "it works" until someone forges a request.

Errors are classified by status and code, never by message text. Meta rewrites its English without notice, and a guard that matches on text goes quietly dead at the next rewording. The default for an unknown code is transient, and that is deliberate: a false terminal loses the customer's message forever, while a false transient spends a few API calls and ends up in a dead-letter queue anyway. The two mistakes do not cost the same.

Contributing

See CONTRIBUTING.md — it says in the first line whether your pull request will be considered.

Security

See SECURITY.md.

License

Apache-2.0. See LICENSE and AUTHORS.

---

Built by Vorluno, extracted from niiko — where it runs in production. Unofficial: not affiliated with, endorsed by, or sponsored by Meta.