Suscripciones por evento (beta)
Registra una URL distinta por tipo de evento vía API, en lugar de una sola en el panel.
Beta
Este esquema está en beta. Es el que usan integraciones como Zapier, y su comportamiento puede cambiar. Para una integración en producción, el webhook único es la vía estable.
En lugar de una URL en el panel que recibe todo, aquí registras una URL por tipo de evento desde la API. Sirve cuando distintos eventos deben ir a distintos destinos — por ejemplo, las firmas a tu backend y los errores de envío a una herramienta de monitoreo.
Cómo cambia el comportamiento
Registrar una suscripción cambia el esquema de toda la cuenta
En cuanto registras la primera suscripción, tu cuenta pasa al esquema de suscripciones y la URL única del panel deja de recibir. A partir de ahí, un evento se entrega solo si tiene una suscripción registrada; los tipos que no suscribas no se entregan.
Por eso conviene planearlo: antes de registrar la primera, ten listas las suscripciones de todos los eventos que hoy procesas. Borrarlas después no regresa la cuenta al esquema anterior — si necesitas volver, escríbenos a [email protected].
Registrar
await services.addWebhook({
url: 'https://tu-servidor.com/hooks/firmas',
type: 'document_completed',
});La respuesta trae el id de la suscripción. Guárdalo: es lo único con lo que puedes darla de baja.
Una URL puede repetirse en varios tipos, y un tipo puede tener varias URLs — se entrega a todas las registradas para ese evento.
// el mismo destino para dos eventos
await services.addWebhook({ url: BACKEND, type: 'document_completed' });
await services.addWebhook({ url: BACKEND, type: 'document_rejected' });
// y los errores de envío a otro lado
await services.addWebhook({ url: MONITOREO, type: 'email_error' });Dar de baja
await services.deleteWebhook({ id: subscriptionId });DELETE /api/v1/webhooks lleva el id en el cuerpo JSON, no en la ruta ni en el query string. Algunos
clientes HTTP omiten el cuerpo en DELETE, así que verifica que el tuyo sí lo mande.
Dar de baja un id que ya no existe también responde correctamente.
Tipos de evento
Los mismos del catálogo: document_completed,
original_signed, universal_signed, document_rejected, workflow_expired, los tres de error de
envío, los dos de NOM-151 y los dos de verificación de identidad.
El esquema WebhookType lista los valores aceptados.
Lo demás no cambia
El sobre de la notificación, la descarga del documento, la política de reintentos y la idempotencia funcionan igual que en el esquema estándar.