Docs

Recibir webhooks

Registra un endpoint y verifica los eventos de tu espacio de trabajo.

También puedes administrar endpoints y entregas desde la consola.

Referencia de eventos

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.

POST /v1/organization/webhook-endpoints/{endpointId}/rotate-secret Rotar secreto de firma del webhook

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

POST /v1/organization/webhook-endpoints/{endpointId}/deliveries/{deliveryId}/replay Reenviar entrega de webhook

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.