Webhooks
Con un webhook, ZarelaFact avisa a tu sistema cuando cambia el estado de un documento o cuando recibes un e-CF de un proveedor. Son opcionales: la consulta por lote siempre funciona y es la fuente para conciliar.
Si integras como Partner, los webhooks son por Partner y cubren a todas tus Cuentas fiscales: ver Webhooks Partner. Esta página es para la cuenta directa.
Crea tu webhook en el portal
- En el portal, abre Desarrolladores → Webhooks.
- Elige arriba el ambiente: pruebas (TesteCF) o producción (eCF). Cada ambiente tiene sus propios endpoints.
- Pulsa Agregar endpoint, escribe la URL de tu receptor y elige Todos los eventos o solo los que vas a usar.
- Copia el secreto de firma que aparece al crearlo. Se muestra una sola vez: guárdalo en tu servidor, nunca en el navegador ni en una app.
- Pulsa Enviar evento de prueba. En unos segundos llega a tu URL un evento
webhook.testfirmado y la entrega aparece en el detalle del endpoint.
Pueden crear y cambiar webhooks el propietario, los administradores y los developers; quien solo lee ve el estado de las entregas, pero no sus cuerpos.
Requisitos de tu receptor
- HTTPS con un certificado válido y accesible desde Internet.
- No puede apuntar a
localhost, a redes privadas ni redirigir a otra dirección. - Debe guardar el evento y responder rápido con cualquier código
2xx.
Eventos
| Evento | Cuándo llega |
|---|---|
document.state_changed | Cambia el estado de uno de tus e-CF (firmado, enviado, aceptado, rechazado…) o aparece un motivo nuevo por el que no avanza (lastError). Solo llega cuando cambia lo que tú ves, no por cada paso interno. |
document.received | Un proveedor te envió un e-CF. Trae el inboundDocumentId para responder la aprobación comercial. |
document.commercial_approval_received | Tu comprador aceptó o rechazó comercialmente un e-CF que emitiste. |
document.commercial_approval_due | Un e-CF que te envió un proveedor sigue sin tu aprobación comercial y faltan 3 días o menos para el plazo (día 15 del mes siguiente a su FechaEmision). Llega una sola vez por e-CF. Los webhooks creados antes no lo reciben hasta que lo agregues a sus eventos. |
annulment.state_changed | La DGII respondió una anulación (ANECF): aceptada, rechazada, fallida o incierta. |
certificate.expiring | Tu certificado digital está por vencer. |
certificate.expired | Tu certificado digital venció. |
dgii.service_degraded | La DGII dejó de responder en ese ambiente (sin respuesta, tiempo de espera, errores 5xx o su autenticación caída): tus envíos quedan en contingencia y se reintentan solos. ZarelaFact revisa la DGII cada minuto y con los envíos de todas las cuentas, así que el aviso te llega aunque no estés enviando (cómo se decide). Llega una vez por episodio, no por documento. data trae state: "degraded", since, code y dgiiEnvironment. |
dgii.service_restored | La DGII volvió a responder en ese ambiente. data trae state: "restored", since y degradedSince. |
dgii.service_slow | La DGII responde pero deja los e-CF «En Proceso» mucho más de lo normal en ese ambiente (DGII lenta). Tus e-CF siguen en camino: no los reenvíes. Llega una vez por episodio, aunque no estés enviando. data trae state: "slow", since, dgiiEnvironment y longestWaitMinutes (lo que más llevaba esperando un e-CF). Los webhooks que ya recibían dgii.service_degraded lo reciben sin cambiar nada; los demás, hasta que lo agregues a sus eventos. |
dgii.service_slow_cleared | La DGII vuelve a resolver los e-CF a tiempo en ese ambiente. data trae state: "normal", since y slowSince. |
webhook.test | Lo envía el botón Enviar prueba. |
Qué recibes
POST /tu-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Zarela-Webhooks/1.0
Zarela-Event-Id: 550e8400-e29b-41d4-a716-446655440000
Zarela-Event-Type: document.state_changed
Zarela-Signature: t=1783706400,v1=...
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "document.state_changed",
"schemaVersion": "webhook.v1",
"createdAt": "2026-10-01T14:00:00.000Z",
"environment": "ecf",
"document": {
"kind": "document",
"id": "8f0c5a5e-1b5c-4c41-9a39-7e0f0b1f2a10",
"encf": "E310000000010",
"documentType": "E31",
"status": "accepted",
"dgiiStatus": "Aceptado",
"trackId": "6a2f1c...",
"printing": {
"securityCode": "Zx9Y8w",
"signatureDate": "01-10-2026 10:00:00",
"qrUrl": "https://ecf.dgii.gov.do/...",
"legends": [],
"pdfUrl": "https://api.zarelafact.com/eCF/documentos-ecf/8f0c5a5e-1b5c-4c41-9a39-7e0f0b1f2a10/pdf"
},
"printingStatus": "available",
"dgiiMessages": [],
"lastError": null,
"contingency": null
}
}
document.statuses el estado del documento en el momento del evento. Desde que la DGII responde (TrackID del e-CF, o Aceptado/Aceptado Condicional del resumen RFCE de una factura de consumo menor a RD$250,000) o el documento entra en contingencia, traeprinting, con lo necesario para la representación impresa. Antes esnullyprintingStatusdice por qué (awaiting_signature,awaiting_dgiiorejected).document.printing.legendstrae las leyendas que lleva el PDF, con su texto literal, ydocument.contingency.startedAtdice desde cuándo el envío se difirió por contingencia (nullsi nunca se difirió). Ambos se mantienen en los eventos siguientes, aunque el documento quedeaccepted. Ver Leyendas.document.printing.pdfUrles la descarga del PDF de la representación impresa por API, con tu API key (ecf:read), igual queGET /{ambiente}/documentos-ecf/{documentId}/pdf. Viene solo cuando la RI ya se entrega.document.lastErrordice por qué el documento no avanza (por ejemploDGII_CERTIFICATE_NOT_DELEGATED, conhint), con los mismos campos que la consulta por lote, incluidoretrying. Esnullsin error o con estado final. Cuando aparece un código nuevo recibes undocument.state_changeduna vez, aunquestatusno haya cambiado.- Un
document.state_changedconstatus: transmission_failed(ylastError.retrying: false) avisa que el envío falló de forma definitiva: la DGII no tiene el documento, ZarelaFact no lo reintenta solo hasta que lo reenvíes y no traeprinting(su representación impresa no se entrega). document.receivedtraedata.inboundDocumentId,data.encfydata.xmlUrl: la descarga del XML del proveedor con tuX-API-KEY(ecf:read), para registrar la compra.document.commercial_approval_receivedtraedata.inboundDocumentId,data.encf(tu e-CF),data.status(acceptedorejected),data.rejectionReason,data.buyerRncydata.correspondence: si el ACECF corresponde con tu e-CF emitido (statusmatched,mismatchcon los campos que difieren enmismatches, oecf_not_found), igual que en la lista de aprobaciones recibidas. Con elinboundDocumentIdconsultas el ACECF y descargas su XML enGET /{ambiente}/aprobaciones-comerciales-recibidas/{inboundDocumentId}.document.commercial_approval_duetraedata.inboundDocumentId(para responder con la aprobación comercial),data.encf,data.issuerRnc,data.issuerName,data.issueDate(FechaEmision,DD-MM-AAAA),data.deadline(AAAA-MM-DD) ydata.daysRemaining(días que faltan, en hora de República Dominicana).annulment.state_changedtraedata.annulmentId,data.status(accepted,rejected,failedouncertain),data.totalAnnulledydata.dgiiCode.certificate.expiringycertificate.expiredtraendata.validToydata.daysRemaining.
Verifica la firma
Calcula un HMAC-SHA256 de {timestamp}.{cuerpo} con el secreto del endpoint y compáralo con los valores v1 de Zarela-Signature:
- Usa el cuerpo crudo exacto, antes de convertirlo a JSON.
- Rechaza timestamps con más de 5 minutos de diferencia.
- Compara en tiempo constante.
- La cabecera puede traer dos
v1mientras conviven el secreto anterior y el nuevo: acepta la entrega si cualquiera coincide. No conviertas la cabecera conObject.fromEntriesni con un mapa clave→valor, porque te quedarías solo con el últimov1.
import { createHmac, timingSafeEqual } from "node:crypto";
// rawBody: Buffer o string con los bytes exactos recibidos.
export function verificarWebhook(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
const header = String(signatureHeader || "");
if (header.length > 512) return false;
const parts = header.split(",").map((part) => part.trim());
const timestamps = parts.filter((part) => /^t=\d+$/.test(part));
const firmas = parts.filter((part) => /^v1=[a-f0-9]{64}$/i.test(part));
if (timestamps.length !== 1 || firmas.length < 1 || firmas.length > 2
|| parts.length !== timestamps.length + firmas.length) return false;
const timestamp = Number(timestamps[0].slice(2));
if (!Number.isSafeInteger(timestamp)) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > toleranceSeconds) return false;
const esperada = createHmac("sha256", secret)
.update(`${timestamp}.`)
.update(rawBody)
.digest();
return firmas.some((part) => timingSafeEqual(esperada, Buffer.from(part.slice(3), "hex")));
}
Si mantienes dos secretos durante un cambio, llama a la función con cada uno y acepta si alguno devuelve true.
Procésalo una sola vez
- Guarda
Zarela-Event-Idcon una restricción única antes de aplicar cambios. Si ya lo procesaste, responde200sin repetir nada. - Si un evento llega tarde o fuera de orden, consulta el estado por lote antes de reemplazar un estado final en tu sistema.
Reintentos
| Respuesta de tu receptor | Qué hace ZarelaFact |
|---|---|
Cualquier 2xx | Entrega exitosa. |
Error de red, timeout (10 s), 408, 429 o 5xx | Reintenta con espera creciente, hasta 8 intentos en total. |
3xx u otro 4xx | Marca la entrega como fallida, sin reintentos. Las redirecciones no se siguen. |
Responde con un cuerpo corto: una respuesta de más de 64 KiB cuenta como fallo.
En el detalle de cada endpoint, Entregas muestra cada envío con su respuesta HTTP o el motivo por el que no llegó (por ejemplo, DNS o tiempo de espera), sus intentos y el próximo reintento. Ver payload muestra el cuerpo enviado y Reenviar vuelve a encolar una entrega fallida o completada con el mismo Zarela-Event-Id.
Edita, rota el secreto, pausa o elimina
- Editar: cambia el nombre y los eventos cuando quieras. Para cambiar la URL, pausa antes el endpoint.
- Rotar: genera un secreto nuevo y lo muestra una sola vez. Durante 24 horas cada entrega viene firmada con los dos secretos (dos
v1enZarela-Signature), así actualizas tu servidor sin perder eventos. - Pausar: los eventos siguen generándose y esperan en cola; salen al Reanudar.
- Eliminar endpoint: deja de recibir eventos y sus entregas en cola se cancelan; el historial se conserva. No se reactiva: si lo necesitas otra vez, agrégalo de nuevo.
Siguiente: Representación impresa.