Webhooks

How Webhooks Work

1. You register your Tavio webhook URL in the third-party provider's dashboard
2. When an event occurs (e.g., a customer sends a message), the provider sends an HTTP POST to your webhook URL
3. Tavio verifies the request signature to ensure it came from the legitimate provider
4. The message is processed through the AI pipeline and a response is sent back via the provider's API

Webhook Endpoints

Signature Verification

Every webhook request is verified before processing. The verification method depends on the provider:

import crypto from "crypto";

function verifyMetaSignature(
  payload: string,
  signature: string,
  appSecret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", appSecret)
    .update(payload)
    .digest("hex");
  return signature === `sha256=${expected}`;
}

Retry Policy

Tavio responds to webhooks as quickly as possible (typically under 200ms for the initial acknowledgment). If your Tavio instance is unavailable, the provider's retry behavior applies:

Payload Format

Each provider sends payloads in their own format. Tavio's channel adapters normalize these into a unified internal message format:

{
  "channel": "whatsapp",
  "senderId": "+254712345678",
  "message": "What is my balance?",
  "messageId": "wamid.abc123",
  "timestamp": "2024-01-15T10:30:00Z",
  "metadata": {
    "phoneNumberId": "123456",
    "profileName": "John Doe"
  }
}

Event Types

Tavio processes the following webhook event types: