Zaira Webhooks

Zaira can send events to your server via webhooks. When you register a webhook, you'll receive a secret - save it, you'll need it to verify incoming requests.

Types

Type	What it does
`RESPONSE`	Zaira's reply to a user message
`ANNOUNCEMENT`	Status updates during longer operations
`WEBHOOK`	Events from external systems (e.g. transaction updates)

Request format

POST /your-endpoint
Content-Type: application/json
x-webhook-signature: <signature>

Payload

All webhook types share the same payload structure:

{
  "uuid": "user-external-uuid",
  "message": "Your current balance is $1,234.56 USD.",
  "attachments": [],
  "execution_id": "execution-uuid"
}

Field	Description
`uuid`	External UUID of the user
`message`	Message text
`attachments`	Array of attachments (may be empty)
`execution_id`	Execution identifier

Signature verification

We sign every request using HMAC-SHA256. The signature is a hex-encoded hash of the raw request body using your webhook secret.

const crypto = require('crypto');

function verifySignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Delivery

Requests timeout after 30 seconds. Return a 2xx status code to acknowledge receipt.

If delivery fails (non-2xx response or timeout), we retry up to 3 times with increasing delays (1s, 2s, 3s between attempts).