Saltar al contenido principal
Los webhooks permiten que tu backend reciba notificaciones de eventos en lugar de hacer polling. Registras un endpoint HTTPS y Telepatia le envía por POST un sobre JSON firmado cada vez que ocurre un evento al que te suscribiste. Cada entrega se firma con HMAC-SHA256 para que puedas comprobar que proviene de Telepatia. Registra un webhook con POST /v1/webhooks; la respuesta devuelve un signingSecret una sola vez: guárdalo de inmediato.

Eventos

Catálogo de eventos

Suscribe cada webhook a uno o más eventos (el array events al crearlo).

Suscribirse a eventos

Envía un array events al registrar un webhook para elegir exactamente qué eventos recibe. El campo type de cada entrega indica qué evento se disparó, así que un mismo endpoint puede manejar todo el ciclo de vida.
Actualiza la suscripción en cualquier momento con PATCH /v1/webhooks/{id} y un nuevo array events.

Estructura del evento

El cuerpo de cada POST de webhook es un sobre JSON. id se mantiene igual entre reenvíos: úsalo para deduplicar. data contiene el objeto de negocio del evento; para los eventos scribe_session.*, es una instantánea de la sesión:
El objeto data para los eventos scribe_session.*: Todos los eventos scribe_session.* envían la misma estructura de data; status refleja el estado real de la sesión y completedAt es null cuando la sesión no se completó. El objeto data para los eventos appointment.*: appointment.fulfilled incluye el scribeSessionId vinculado; appointment.cancelled trae scribeSessionId en null.

Verificar la firma

Cada solicitud lleva un encabezado X-Scribe-Api-Signature (estilo Stripe):
t es la marca de tiempo Unix en que se firmó la solicitud; v1 es el HMAC-SHA256 en hexadecimal de "{t}." + raw_request_body, usando tu secreto de firma como clave. Verifica sobre el cuerpo crudo de la solicitud antes de parsearlo: volver a serializar el JSON puede cambiar los bytes y romper la comparación. Usa una comparación de tiempo constante y rechaza marcas de tiempo fuera de una ventana de 5 minutos para mitigar ataques de repetición.
Cada solicitud también lleva X-Scribe-Api-Event-Id (igual al id del evento) para facilitar el registro en logs.

Reintentos y entrega

  • Devuelve un 2xx rápidamente para confirmar la recepción. Haz el trabajo lento de forma asíncrona.
  • Un 5xx, error de red o timeout se reintenta con backoff exponencial (de ≈2 s hasta ≈2 min entre intentos), con un máximo de 6 intentos a lo largo de ~15 minutos.
  • Cualquier 4xx (incluidos 408 y 429) se trata como permanente: la entrega no se reintenta.
  • Los reintentos reutilizan el mismo id del evento, así que úsalo para deduplicar y mantener la idempotencia.

Rotar el secreto de firma

Llama a POST /v1/webhooks/{id}/rotate-secret para generar un nuevo secreto. La respuesta devuelve el nuevo signingSecret una sola vez e incrementa signingSecretVersion. El secreto anterior deja de ser válido para verificar de inmediato, así que despliega el nuevo valor en tu endpoint antes de rotar.