Ir al contenido

Webhooks

Un webhook es una URL de tu sistema a la que enviamos un POST cada vez que pasa algo. Es la forma recomendada de seguir el estado de tus comprobantes.

En el portal, Webhooks → Crear (Owner o Admin):

  • URL: https:// y accesible desde Internet.
  • Eventos: los que quieres recibir (o todos).
  • Ambientes: por defecto solo producción (Ecf). Para recibir los de tu empresa de pruebas, agrega TestEcf.

El secreto (whsec_…) se muestra una sola vez. Guárdalo: sirve para verificar la firma. Si se filtra, rótalo en el portal (el anterior deja de valer de inmediato).

Evento Cuándo data
invoice.status_changed Cada cambio de estado de un comprobante invoiceId, companyId, environment, ecfType, encf, version, previousStatus, status, trackId, securityCode, timbreUrl, dgii (code, status, sequenceConsumed)
invoice.contingency La DGII no respondió al enviarlo Lo anterior y contingency (since, deadline, legend). Ver Contingencia.
invoice.delivered El comprobante llegó al comprador (acuse de su receptor electrónico, o correo enviado) channel, status, target, acknowledgement
invoice.receiver_unconfirmed Un comprobante de producción debía llegar al buzón de su comprador (receptor electrónico) y no tenemos su URL de recepción: agrégala al cliente en el catálogo. No llega si la DGII indica que el comprador no es receptor electrónico deliveryId, buyerRnc, buyerName
commercial_approval.received El comprador aprobó o rechazó comercialmente un e-CF buyerRnc, decision, reason
received_invoice.created Recibiste un e-CF de un proveedor issuerRnc, issuerName, ecfType, encf, issueDate, total

Ignora los eventos que no conozcas: podemos agregar nuevos.

POST /tu/webhook HTTP/1.1
Content-Type: application/json
X-Webhook-Id: 3b0e… ← único por entrega: úsalo para no procesarla dos veces
X-Webhook-Event: invoice.status_changed
X-Webhook-Timestamp: 1763302502
X-Webhook-Signature: t=1763302502,v1=5d41402abc4b2a76b9719d911017c592…
{"id":"3b0e…","type":"invoice.status_changed","createdAt":"2026-11-16T14:15:04Z",
"data":{"invoiceId":"8f6c…","environment":"Ecf","encf":"E310000000001","previousStatus":"Sent","status":"Accepted", …}}

v1 es HMAC-SHA256(secreto, "{timestamp}.{cuerpo}") en hexadecimal, calculado sobre el cuerpo exacto (los bytes recibidos, antes de deserializarlo). Compara en tiempo constante y rechaza timestamps de hace más de 5 minutos.

Ventana de terminal
# Para revisar a mano una entrega guardada: cuerpo.json con los bytes exactos recibidos.
TIMESTAMP=1763302502 # el t= de X-Webhook-Signature
printf '%s.' "$TIMESTAMP" | cat - cuerpo.json \
| openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -hex | awk '{print $NF}'
# Debe coincidir con el v1= de X-Webhook-Signature.
  • Responde 2xx rápido (en pocos segundos) y procesa después, en segundo plano.
  • Si no respondes 2xx, reintentamos a 1 min, 5 min, 30 min, 2 h, 6 h y 24 h. Después la entrega queda agotada; puedes reintentarla a mano en el portal.
  • Una entrega puede llegar más de una vez: deduplica por X-Webhook-Id.
  • El orden no está garantizado: usa status (y, si hace falta, consulta el comprobante), no el orden de llegada.
  • Actúa solo con los estados finales: Accepted, AcceptedConditional y Rejected.