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.
Configurarlo
Sección titulada «Configurarlo»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, agregaTestEcf.
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).
Eventos
Sección titulada «Eventos»| 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.
La solicitud
Sección titulada «La solicitud»POST /tu/webhook HTTP/1.1Content-Type: application/jsonX-Webhook-Id: 3b0e… ← único por entrega: úsalo para no procesarla dos vecesX-Webhook-Event: invoice.status_changedX-Webhook-Timestamp: 1763302502X-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", …}}Verificar la firma
Sección titulada «Verificar la firma»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.
# Para revisar a mano una entrega guardada: cuerpo.json con los bytes exactos recibidos.TIMESTAMP=1763302502 # el t= de X-Webhook-Signatureprintf '%s.' "$TIMESTAMP" | cat - cuerpo.json \ | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -hex | awk '{print $NF}'# Debe coincidir con el v1= de X-Webhook-Signature.using System.Security.Cryptography;using System.Text;
static bool Verify(string secret, string signatureHeader, string body){ var parts = signatureHeader.Split(',').Select(p => p.Split('=', 2)).ToDictionary(p => p[0], p => p[1]); var timestamp = long.Parse(parts["t"]); if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - timestamp) > 300) return false; var expected = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes($"{timestamp}.{body}")); return CryptographicOperations.FixedTimeEquals(expected, Convert.FromHexString(parts["v1"]));}import { createHmac, timingSafeEqual } from "node:crypto";
function verify(secret, signatureHeader, rawBody) { const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=", 2))); if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false; const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest(); const received = Buffer.from(parts.v1, "hex"); return received.length === expected.length && timingSafeEqual(expected, received);}Responder y reintentos
Sección titulada «Responder y reintentos»- 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,AcceptedConditionalyRejected.