Skip to content
Firmeasy Logo Firmeasy API Documentation

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.

Endpoint

POST 
https://app.firmeasy.legal/api/v1/webhooks

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

Nombre 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ámetrosy)

Nombre 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",
  "event": "signer_rejected"
}

Campos devueltos

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.
signed_headers array/null Headers firmados (por ahora null).
created_at datetime Fecha de creación.
updated_at datetime Última actualización.

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",
  "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"
}