---
title: "Recibir webhooks"
description: "Registra un endpoint y verifica los eventos de tu espacio de trabajo."
language: es-MX
canonical_url: "https://exac.mx/docs/webhooks"
md_url: "https://exac.mx/docs/webhooks.md"
---

# Recibir webhooks

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

[Referencia de eventos](/docs/webhooks/events)

[También puedes administrar endpoints y entregas desde la consola.](/consola/webhooks)

## 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](/docs/api/workspace/credentials/create-webhook-endpoint)

```bash
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.

```javascript
import { Webhook } from "standardwebhooks";

function verifyWebhook(rawBody, headers, secret) {
  return new Webhook(secret).verify(rawBody, headers);
}
```

```python
from standardwebhooks.webhooks import Webhook

def 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}](/docs/api/workspace/credentials/update-webhook-endpoint)

## 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](/docs/api/workspace/credentials/rotate-webhook-endpoint-secret)

## 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](/docs/api/workspace/credentials/test-webhook-endpoint)

[GET /v1/organization/webhook-endpoints/{endpointId}/deliveries](/docs/api/workspace/credentials/list-webhook-deliveries)

[POST /v1/organization/webhook-endpoints/{endpointId}/deliveries/{deliveryId}/replay](/docs/api/workspace/credentials/replay-webhook-delivery)

## 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.

Documentación completa: https://exac.mx/docs.md
Índice para agentes: https://exac.mx/docs/llms.txt
