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 arrayevents 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.
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:
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 encabezadoX-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.
X-Scribe-Api-Event-Id (igual al id del evento) para facilitar el registro en logs.
Reintentos y entrega
- Devuelve un
2xxrá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(incluidos408y429) se trata como permanente: la entrega no se reintenta. - Los reintentos reutilizan el mismo
iddel evento, así que úsalo para deduplicar y mantener la idempotencia.
Rotar el secreto de firma
Llama aPOST /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.