Cómo funcionan
Firmame te avisa cuando algo pasa; tú usas ese aviso para descargar el documento.
Un webhook es una URL tuya a la que Firmame hace POST cuando ocurre algo: alguien firmó, el documento
se completó, una invitación rebotó. Es la alternativa a estar consultando el estado cada tanto.
Configurar tu URL
Entra a tu cuenta de desarrollador en firmamex.com/developers/login y registra ahí la URL. Es una sola por cuenta, y recibe todas las notificaciones de tus documentos.
La URL tiene que aceptar POST con Content-Type: application/json.
El ciclo
La notificación no trae el documento, trae el firmamex_id con el que lo pides. Esa segunda
llamada va autenticada como cualquier otra.
Lo que llega
Todos los eventos comparten el mismo sobre:
{
"notification_type": "document_completed",
"notification_id": "2698",
"firmamex_id": "04337396-e929-43ca-9b8a-ec958a44079d",
"document_title": "contrato.pdf",
"text": "Document 04337396-… has been completed"
}| Campo | Qué es |
|---|---|
notification_type | Qué pasó |
notification_id | Id único de la notificación |
firmamex_id | El id del documento — el mismo document_ticket de cuando lo creaste |
document_title | El nombre del archivo |
meta | Solo en algunos eventos; lleva el detalle específico |
Los eventos de firma traen además signer_email, signer_fingerprint y signer_data.
Como llegan todos los tipos a la misma URL, discrimina por notification_type al recibir.
Obtener el documento
Con el firmamex_id de la notificación descargas el documento firmado en
GET /api/document/{type}/{ticket}, eligiendo type:
original para el PDF con las firmas tal como se aplicaron, o universal para esas mismas firmas
envueltas en un sobre de validación a largo plazo.
const pdf = await services.downloadDocument(firmamexId, 'original');Original y universal son dos representaciones firmadas del mismo documento; la diferencia está en Conceptos.
Qué evento escuchar
Para la mayoría de las integraciones, document_completed es el único que importa: se dispara cuando
ya firmaron todos y el documento está listo.
original_signed llega una vez por cada firma, así que en un documento de tres firmantes lo vas a
recibir tres veces. Úsalo si quieres mostrar avance parcial; no lo uses para disparar tu proceso de
negocio.
Los eventos de error —email_error, sms_error, whatsapp_error— avisan que una invitación no llegó.
Vale la pena atenderlos: sin ellos, un correo mal escrito se ve igual que un firmante que se está
tardando.
El catálogo completo, con el payload de cada uno, está en la referencia.
Qué espera Firmame de tu endpoint
- Responde
200. Cualquier otra cosa cuenta como fallo. - Responde rápido. Si vas a hacer trabajo pesado, encólalo y contesta el
200de inmediato. - Responde
200también cuando llegue un evento que no esperabas. Los tipos nuevos no deberían tumbar tu endpoint.
Reintentos
Si tu servidor no contesta 200, Firmame reintenta con backoff exponencial:
10 segundos + min(2 ^ intentos, 600) + jitterEl tiempo entre intentos crece hasta un máximo de 600 segundos (10 minutos), con hasta 30 intentos. En la práctica eso te da varias horas de margen para levantar un servicio caído sin perder notificaciones.
Una URL inválida no se reintenta. Si el registro apunta a un host que no resuelve, no hay nada que reintentar — vale la pena verificar la URL al registrarla.
Idempotencia
notification_id es único por notificación. Guárdalo al procesar y descarta los repetidos: es la forma
más simple de que un reintento no cobre dos veces, no mande dos correos, ni cree dos registros.
Probarlo
Durante el desarrollo, un túnel hacia tu máquina (ngrok, Cloudflare Tunnel o similar) te deja registrar una URL pública que apunta a tu servidor local y ver las notificaciones llegar de verdad.
Suscripciones por evento
Existe además un esquema de suscripciones, donde registras una URL distinta por tipo de evento vía API en lugar de una sola en el panel. Es lo que usan integraciones como Zapier, y está en beta.