Webhooks

Los endpoints de larga duración pueden entregar sus resultados a una URL de webhook de tu elección en lugar de mantener abierta la conexión HTTP. Así funciona exclusivamente /v1/rfc/verify-batch, y es una opción en /v1/rfc/validate, /v1/rfc/find-zip y /v1/rfc/commerce-registry.

Cómo funciona

• Envía webhook_url en el cuerpo de la solicitud. Solo http o https. No se siguen redirecciones. Longitud máxima: 2048 caracteres.
• El API devuelve de inmediato un 202 Accepted con un pequeño envoltorio de estado y luego sigue procesando.
• Cuando el SAT responde, enviamos un payload JSON vía POST a tu URL. El envoltorio status/body del payload refleja la respuesta síncrona.

Estructura del payload

{
  "status": 200,
  "body": {
    "rfc": "XAXX010101000",
    "valid": true,
    "message": "RFC válido, puede ser utilizado en comprobantes",
    "...": "rest of the endpoint's normal response body"
  }
}

Recibir webhooks

• Responde con cualquier estado 2xx lo más rápido posible. Cualquier otra cosa la tratamos como un fallo de entrega.
• Los webhooks son best-effort. Cada resultado se envía una sola vez, con un tiempo límite de 30 segundos, y no se reintenta, así que mantén tu endpoint disponible.
• Siempre valida que el rfc del cuerpo coincida con una solicitud que enviaste. No confíes en el payload del webhook para identificar a qué usuario pertenece; usa una URL acotada por tenant o incluye un token en la ruta.

Pruebas locales

Usa un túnel como ngrok, Cloudflare Tunnel o Tailscale Funnel para exponer tu servidor de desarrollo local. No necesitamos alcanzarte dentro de una red privada. Cualquier URL resoluble públicamente funciona.