whatsapp-webhooks

WhatsApp Webhooks

Receive webhooks from the WhatsApp Business Platform (Cloud API), delivered by Meta's Graph API. WhatsApp webhooks are Meta webhooks: they require a one-time GET verification handshake and sign every POST with X-Hub-Signature-256. They do not follow the Standard Webhooks spec.

When to Use This Skill

• How do I receive WhatsApp webhooks?
• How do I complete the WhatsApp / Meta webhook verification handshake (hub.challenge)?
• How do I verify the WhatsApp X-Hub-Signature-256 signature?
• Why is my WhatsApp webhook signature verification failing?
• How do I handle inbound WhatsApp messages vs. message status updates?

Two Things Every Endpoint Must Do

1. GET handshake — When you register the endpoint, Meta sends a GET with hub.mode=subscribe, hub.verify_token, and hub.challenge. If the mode is subscribe and the token matches your configured verify token, respond 200 with the raw hub.challenge value as the body (no JSON, no quotes).
2. POST signature check — Every event POST carries X-Hub-Signature-256: sha256=<hex>. Compute HMAC-SHA256 over the raw request body using your app secret and compare timing-safe.

Verification (core)

Compute HMAC-SHA256 over the raw bytes of the request body keyed on your Meta app secret, then compare against the hex digest after sha256=. Use the raw body exactly as received — Meta escapes non-ASCII characters (e.g. é), so re-serializing parsed JSON produces a different, failing digest.

Node:

const crypto = require('crypto');

function verifyWhatsAppSignature(rawBody, signatureHeader, appSecret) {
  const [algo, sig] = (signatureHeader || '').split('=');
  if (algo !== 'sha256' || !sig) return false;
  const expected = crypto.createHmac('sha256', appSecret).update(rawBody).digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex'));
  } catch {
    return false; // length mismatch = invalid
  }
}