Webhooks

Cada entrega es un POST con el evento JSON como cuerpo y dos headers: `horato-event` (el tipo de evento) y `horato-signature` con la forma `t=<timestamp>,v1=<firma>`. La firma es `HMAC-SHA256(secret, "<timestamp>.<cuerpo_crudo>")` en hex, usando el secreto de firma que se devuelve una sola vez al crear el webhook.

Verifica sobre el cuerpo crudo antes de parsear JSON, compara firmas en tiempo constante y rechaza timestamps de más de unos minutos para reducir el riesgo de replay. Los nombres antiguos `x-okcal-event` / `x-okcal-signature` se envían como alias para consumidores que verificaban contra los nombres previos al rebrand.

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);

Suscribe un webhook a tipos de evento específicos, u omite el filtro para recibirlos todos. Los eventos se nombran por dominio.

• Conexiones: `connection.reauth_required`.
• Email: `email.received`, `email.sent`, `email.draft.created`, `email.draft.updated`.
• Agendamiento: `scheduling.booking.created`, `scheduling.booking.rescheduled`, `scheduling.booking.cancelled`.
• Grabación: `recording.bot.started`, `recording.meeting.status_change`, `recording.transcript.updated`, `recording.recording.completed`.
• La lista completa y vigente está en `/docs/openapi.json` y en la columna de eventos de la referencia.

Horato reintenta entregas fallidas con backoff exponencial y mueve los eventos agotados a una cola dead-letter. Usa el inspector cuando un receptor devuelva un estado distinto de 2xx: arregla el receptor, reproduce la entrega y luego limpia las colas dead-letter de forma intencional.

• Lista entregas con `/v1/webhooks/deliveries`.
• Reproduce una entrega con `/v1/webhooks/deliveries/{delivery_id}/replay`.
• Reencola eventos dead-letter con `/v1/webhooks/dead-letter/{event_id}/requeue`.