Saltar al contenido principal
La URL de tu webhook es pública, así que cualquiera que la conozca puede enviarle solicitudes. Ciarem firma cada solicitud con el secreto de firma de tu endpoint. Comprobar esa firma es la forma en que tu servidor distingue un evento real de Ciarem de uno falsificado. Verifica antes de confiar en el cuerpo.

El secreto de firma

Cada endpoint tiene su propio secreto. Empieza con whsec_.
  • En el panel: se muestra cuando agregas el endpoint, y de nuevo en cualquier momento en la página del endpoint con Mostrar secreto. Solo los administradores pueden verlo.
  • Con la API: se devuelve una sola vez, en la respuesta de POST /v1/webhook-endpoints.
Trátalo como una contraseña: guárdalo en tu gestor de secretos o en una variable de entorno, nunca en el código ni en un navegador.

El encabezado de firma

Cada solicitud lleva un encabezado Ciarem-Signature:
La firma se calcula sobre la marca de tiempo, un punto y el cuerpo sin procesar de la solicitud, usando tu secreto de firma como clave:

Cómo verificar

1

Lee el cuerpo sin procesar

Toma el cuerpo de la solicitud exactamente como llegaron los bytes, antes de parsear el JSON. Parsear y volver a serializar cambia los espacios y el escapado de caracteres, y la firma ya no coincidirá.
2

Separa el encabezado

Separa Ciarem-Signature por , y luego por = para obtener t y v1.
3

Calcula la firma esperada

Arma el mensaje t + "." + raw body y calcula su HMAC-SHA256 con tu secreto de firma. Usa el secreto completo, incluido el prefijo whsec_, tal como está.
4

Compara de forma segura

Compara tu resultado con v1 usando una función de comparación en tiempo constante, no ==.
5

Revisa la marca de tiempo

Rechaza la solicitud si t está a más de 5 minutos del reloj de tu servidor. Esto evita que alguien capture una solicitud real y la reenvíe más tarde.
Si algún paso falla, responde 400 y no hagas nada con el cuerpo.

Código que puedes copiar

Prueba tu código con un ejemplo conocido

Usa estos valores para confirmar que tu código de verificación calcula la firma correcta, sin esperar un evento real. Sáltate la revisión de la marca de tiempo mientras ejecutas esto, porque la marca de tiempo del ejemplo está en el pasado. Puedes producir el mismo valor desde una terminal:

Si la firma no coincide

Buenas prácticas

  • Un secreto por endpoint. Si tienes servidores de staging y de producción, dale a cada uno su propio endpoint, para que un secreto de staging filtrado no pueda falsificar eventos de producción.
  • Rota reemplazando el endpoint. Un secreto no se puede cambiar en el mismo endpoint. Para rotar, agrega un endpoint nuevo con la misma URL y los mismos eventos, actualiza tu servidor para que acepte el secreto nuevo y luego elimina el endpoint antiguo. Mientras existan los dos, recibes cada evento dos veces, una por endpoint, con el mismo id de evento, así que deduplicar por id hace que esto no cause problemas.
  • Cada reintento se firma de nuevo. Una entrega reintentada tiene el mismo cuerpo y el mismo id de evento, pero un t nuevo y una firma nueva, así que la revisión de 5 minutos también funciona para los reintentos.
  • La verificación prueba el origen, no la unicidad. Un evento verificado todavía puede ser un duplicado. Deduplica también por id.