Crear Webhook

POST {{base_url}}/v1/webhooks

curl -X POST {{base_url}}/v1/webhooks \
-H "Authorization: Bearer TU_TOKEN_AQUI" \
-H "Content-Type: application/json" \
-d '{
  "target_url": "https://hooks.tuempresa.com/events/firmeasy",
  "event": "document_signed"
}'

Sin ejecutar·latencia ~ 412 ms

Demo pública · no guarda datos · firma con sandbox PKI

Crear Webhook

Permite registrar un webhook para recibir notificaciones automáticas cuando ocurra un evento específico (por ejemplo, cuando un documento sea firmado o un firmante rechace).

Al crear el webhook, Firmeasy devuelve un secret_key único. Este secreto será utilizado para firmar todos los payloads enviados al target_url, permitiendo verificar la autenticidad mediante HMAC-SHA256.

¿Por qué utilizamos HMAC?

El estándar HMAC (Hash-based Message Authentication Code) se emplea para garantizar la integridad y autenticidad de las notificaciones enviadas a tu target_url.

Cuando Firmeasy dispara un webhook, calcula un hash del contenido (payload) utilizando la secret_key única de tu webhook. Esto permite:

✅ Asegurarte de que la solicitud fue realmente enviada por Firmeasy.
✅ Verificar que el contenido no fue alterado en tránsito.
✅ Rechazar mensajes no firmados o manipulados.

Para implementar la validación en tu servidor receptor, solo debes recalcular el HMAC con tu clave secreta (secret_key) y comparar el resultado con el hash recibido en el header. Así puedes tener confianza total en la integridad del evento.

Campos Obligatorios

Los campos marcados con un asterisco (*) son obligatorios y deben ser proporcionados en la solicitud. Los demás campos son opcionales.

Headers requeridos

Parámetro	Tipo	Descripción	Límites
`Authorization*`	string	Token de acceso obtenido en el login, con el prefijo 'Bearer'.	Obligatorio
`Content-Type`	string	Especifica el tipo de contenido del cuerpo de la solicitud HTTP. Para las peticiones que incluyen datos JSON	'application/json'

Cuerpo de la solicitud (Parámetros)

Parámetro	Tipo	Descripción	Límites
`target_url*`	string	URL destino a la que se enviarán los eventos cuando ocurra el trigger.	Obligatorio
`event*`	string	Evento que activará el webhook. Ej: 'document_signed' o 'signer_rejected'.	Obligatorio

Ejemplo de request

{
  "target_url": "[https://hooks.empresaglobal.com/events/9d4f7a2c-35e1-4a8b-9216-bc0f3f6b2b93](https://hooks.empresaglobal.com/events/9d4f7a2c-35e1-4a8b-9216-bc0f3f6b2b93)",
  "event": "signer_rejected"
}

Ejemplo de respuesta

{
  "id": "c4e51f28-7a91-45c0-a918-2b84f8a14e57",
  "user": "6b2fcd91-3d78-4a19-80fa-50d2ac93e481",
  "document": null,
  "event": "signer_rejected",
  "target_url": "[https://hooks.empresaglobal.com/events/c4e51f28-7a91-45c0-a918-2b84f8a14e57](https://hooks.empresaglobal.com/events/c4e51f28-7a91-45c0-a918-2b84f8a14e57)",
  "active": true,
  "secret_key": "92JF4PLX8MK1S0AGB2VY5HQ7N",
  "custom_headers": null,
  "signed_headers": null,
  "type": "E",
  "created_at": "2024-12-18T10:22:45.000000Z",
  "updated_at": "2024-12-18T10:22:45.000000Z"
}

Nombre	Tipo	Descripción
`id`	string	Identificador único del webhook en Firmeasy.
`user`	string	ID del usuario que es propietario del webhook.
`document`	string/null	Documento asociado si aplica, o null.
`event`	string	Evento configurado que disparará el webhook.
`target_url`	string	URL destino configurada.
`active`	boolean	Indica si el webhook está activo.
`secret_key`	string	Clave secreta única que sirve para firmar los payloads con HMAC.
`custom_headers`	object/null	Headers personalizados si aplican, o null.
`signed_headers`	array/null	Headers firmados (por ahora null).
`type`	string	Tipo de webhook configurado.
`created_at`	datetime	Fecha de creación.
`updated_at`	datetime	Última actualización.

Errores posibles

Código	Estado	Descripción
`400`	Bad Request	Parámetros inválidos o faltantes.
`401`	Unauthorized	No autorizado. Token inválido o ausente.
`409`	Conflict	Conflicto. Webhook duplicado.
`422`	Unprocessable Entity	Error de validación en los datos enviados.
`500`	Internal Server Error	Error interno inesperado.