Webhooks

Each delivery is a POST with the JSON event as the body and two headers: `horato-event` (the event type) and `horato-signature` in the form `t=<timestamp>,v1=<signature>`. The signature is `HMAC-SHA256(secret, "<timestamp>.<raw_body>")`, hex-encoded, using the signing secret returned once when you create the webhook.

Verify over the raw request body before parsing JSON, compare signatures in constant time, and reject timestamps older than a few minutes to reduce replay risk. The legacy `x-okcal-event` / `x-okcal-signature` header names are still sent as aliases for consumers that verified against the pre-rebrand names.

import crypto from "node:crypto";

function verifyHoratoWebhook(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const ok = crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return ok && fresh;
}

verifyHoratoWebhook(rawBody, req.headers["horato-signature"], process.env.HORATO_WEBHOOK_SECRET);

Subscribe a webhook to specific event types, or omit the filter to receive all of them. Events are namespaced by domain.

• Connections: `connection.reauth_required`.
• Email: `email.received`, `email.sent`, `email.draft.created`, `email.draft.updated`.
• Scheduling: `scheduling.booking.created`, `scheduling.booking.rescheduled`, `scheduling.booking.cancelled`.
• Recording: `recording.bot.started`, `recording.meeting.status_change`, `recording.transcript.updated`, `recording.recording.completed`.
• The complete, current list is in `/docs/openapi.json` and the events column of the API reference.

Horato retries failed deliveries with exponential backoff and moves exhausted events to a dead-letter queue. Use the delivery inspector when a receiver returns a non-2xx status: fix the receiver, replay the delivery, then clear dead-letter queues intentionally.

• List deliveries with `/v1/webhooks/deliveries`.
• Replay one delivery with `/v1/webhooks/deliveries/{delivery_id}/replay`.
• Requeue dead-lettered events with `/v1/webhooks/dead-letter/{event_id}/requeue`.