Webhooks

Get new messages, delivery results and number changes on your server as they happen.

Events

Each request is a POST with a JSON body containing event, created_at and data.

Event	Sent when
message.received	Someone messages one of your numbers
message.sent	Your message was handed to WhatsApp
message.failed	A message couldn’t be sent. data.error says why
number.connected	A number finished linking
number.disconnected	A number was logged out from the phone

Add an endpoint

1Open WhatsApp → Webhooks and choose Add endpoint.
2Enter your https URL and pick the events.
3Copy the signing secret (whsec_…).
4Choose Send test event and check Recent deliveries.

Verify the signature

Every request has X-Rimbra-Event, X-Rimbra-Timestamp and X-Rimbra-Signature headers. The signature is sha256= followed by the HMAC-SHA256 of "{timestamp}.{raw body}" with your signing secret.

javascript

import crypto from "crypto"

export function verifyRimbra(rawBody, headers, secret) {
  const timestamp = headers["x-rimbra-timestamp"]
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex")
  const given = headers["x-rimbra-signature"] || ""
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))
}

Retries

Answer with a 2xx status within 10 seconds.
Failed deliveries are retried up to three times, waiting longer each time.
Every attempt shows under Recent deliveries with the response code.
Pause an endpoint with its switch while you fix your server.