Recibir webhooks
Registra un endpoint y verifica los eventos de tu espacio de trabajo.
También puedes administrar endpoints y entregas desde la consola.
Registra el endpoint
Usa una API key con acceso full. La administración requiere apiKeys:manage y está disponible solo en REST, no en MCP. Envía Authorization: Bearer <API_KEY> y una Idempotency-Key distinta por escritura; conserva esa misma clave al reintentar.
Guarda data.secret de la respuesta en tu gestor de secretos. Solo se muestra al crear o rotar, nunca al consultar. Elige eventTypes del catálogo. issuerRfcs es opcional; omítelo para recibir todos los RFC o envía null al actualizar para quitar el filtro.
Los endpoints pertenecen al espacio de trabajo. Una API key cubre todos sus RFC y cada evento indica su issuer.
POST /v1/organization/webhook-endpoints Crear endpoint de webhooks
curl -X POST "https://api.sandbox.exac.mx/v1/organization/webhook-endpoints" \ -H "Authorization: Bearer <EXAC_API_KEY>" \ -H "Idempotency-Key: 2f6b0e7a-5c1d-4e3a-9b8f-7d4a1c9e6b52" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks", "eventTypes": [ "sat_sync.completed" ] }'Verifica la firma
Instala la biblioteca oficial con npm install standardwebhooks o pip install standardwebhooks. Exac usa Standard Webhooks y secretos whsec_.
Pasa el cuerpo crudo, sin parsear ni volver a serializar, y los encabezados webhook-id, webhook-timestamp y webhook-signature a la biblioteca. Desactiva el parser JSON de tu framework para esta ruta o captura los bytes antes de que corra. Rechaza la solicitud si la verificación falla.
import { Webhook } from "standardwebhooks";function verifyWebhook(rawBody, headers, secret) { return new Webhook(secret).verify(rawBody, headers);}from standardwebhooks.webhooks import Webhookdef verify_webhook(raw_body, headers, secret): return Webhook(secret).verify(raw_body, headers)Confirma y procesa después
Verifica, guarda el evento de forma duradera y responde con 2xx antes de 15 segundos. Haz el trabajo en segundo plano. La entrega es al menos una vez y no respeta un orden.
Deduplica con webhook-id, que coincide con el id del evento y no cambia entre reintentos ni reenvíos. Guarda el id junto con el trabajo pendiente de forma atómica. No devuelvas éxito si perderías el evento al reiniciar.
Reintentos y desactivación
Tras un fallo, los intervalos de reintento son 5 segundos, 5 minutos, 30 minutos, 2 horas, 5 horas, 10 horas y 10 horas, contados desde cada fallo. Puede haber esperas adicionales por la cola y la pausa del endpoint.
Una respuesta 410 desactiva el endpoint de inmediato. Un intento fallido tras 5 días sin éxitos también lo desactiva. Exac envía un correo a los administradores del espacio de trabajo. Un éxito reinicia el periodo de fallos.
Corrige el receptor y actualiza status a enabled. Esto reanuda las entregas pendientes que no hayan caducado. Las entregas que agotaron sus intentos necesitan un reenvío.
PATCH /v1/organization/webhook-endpoints/{endpointId} Actualizar endpoint de webhooks
Rota el secreto
Guarda el nuevo data.secret al rotar. Exac firma con ambos secretos durante 1 día, así que puedes actualizar el receptor sin interrumpirlo. Rotar otra vez elimina de inmediato el secreto más antiguo. La rotación no habilita un endpoint desactivado.
Prueba y depura
Envía un evento de prueba al endpoint habilitado. Elige eventType e issuer; la prueba ignora sus filtros de suscripción. Los datos son ejemplos con ids que no corresponden a documentos reales.
Consulta las entregas para ver su estado, último intento y evento. Pagina hasta que pagination.hasMore sea false. Reenviar crea otra entrega con el mismo id de evento y pasa por la cola y la firma normales. El evento debe seguir retenido.
POST /v1/organization/webhook-endpoints/{endpointId}/test Enviar evento de webhook de prueba
GET /v1/organization/webhook-endpoints/{endpointId}/deliveries Listar entregas de webhooks
Requisitos y límites
Solo HTTPS y direcciones públicas accesibles desde internet. Exac no sigue redirecciones. Máximo 10 endpoints por espacio de trabajo y 100 RFC por filtro. Los eventos y las entregas caducan a los 30 días.
Exac solo registra eventos cuando existe un endpoint habilitado que los acepta. No hay un historial global previo a la suscripción.
Prueba y producción
Sandbox y producción son despliegues separados. Registra tus endpoints en cada uno con la API key de ese entorno. El ejemplo de alta usa sandbox.