How to send Replai events to your own system with webhooks

Webhooks are for businesses that already run software and want Replai's events in it: a ticketing system, a CRM, an internal dashboard, a pager rota.

The four events

message.inbound fires for every incoming customer message, after it has been stored. High volume on a busy number.

message.outbound fires when a reply lands on WhatsApp. This includes away messages, not just AI replies, so check the payload rather than assuming everything on this event came from the model.

conversation.taken_over fires when a person takes a thread over from the bot. Useful for measuring how often the bot hands off, which is the single most honest quality metric you have.

flag.created fires when a conversation is classified as needing a person.

If you wire up one event, make it flag.created. It is the machine-readable version of the escalation email, and it is the one where reacting in software actually beats reacting in an inbox: open a ticket, page whoever is on duty, put a row in your own system.

Verifying the signature

Every request carries an X-Replai-Signature header containing an HMAC-SHA256 of the body, computed with your secret.

Verify it before you trust anything in the payload. An endpoint that accepts whatever is posted to it is an endpoint anybody can post to, and the events carry customer messages.

The one implementation detail that trips people up: sign the raw body bytes, not a re-serialised version of the parsed JSON. Parsing and re-stringifying changes key order and whitespace, the bytes differ, and the signature will never match no matter how correct the rest of your code is.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, header, secret) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  const got = header.replace(/^sha256=/, '');
  const a = Buffer.from(expected);
  const b = Buffer.from(got);
  return a.length === b.length && timingSafeEqual(a, b);
}

Use a timing-safe comparison rather than ===. It costs nothing and removes a whole class of attack on the secret.

Return quickly

Acknowledge the request, then do your work.

Anything slow inside the handler, writing to a database that is under load, calling another API, sending an email, turns into a webhook that is still open when the next one arrives. Take the payload, put it on a queue, return 200.

Webhooks are notifications, not a log

Deliveries can fail. There is no replay.

That is fine for reacting to things, and wrong for anything that must be complete. If a missed flag would be a real problem, reconcile periodically against the conversation list rather than trusting the stream to have delivered everything.

What to do next

That is every integration. The remaining guides are about running the thing day to day: taking threads over, reading what got flagged, and keeping an eye on usage.