Saltar al contenido principal

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​

  1. En el portal, abre Desarrolladores → Webhooks.
  2. Elige arriba el ambiente: pruebas (TesteCF) o producción (eCF). Cada ambiente tiene sus propios endpoints.
  3. Pulsa Agregar endpoint, escribe la URL de tu receptor y elige Todos los eventos o solo los que vas a usar.
  4. 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.
  5. Pulsa Enviar evento de prueba. En unos segundos llega a tu URL un evento webhook.test firmado 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​

EventoCuándo llega
document.state_changedCambia 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.receivedUn proveedor te envió un e-CF. Trae el inboundDocumentId para responder la aprobación comercial.
document.commercial_approval_receivedTu comprador aceptó o rechazó comercialmente un e-CF que emitiste.
document.commercial_approval_dueUn 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_changedLa DGII respondió una anulación (ANECF): aceptada, rechazada, fallida o incierta.
certificate.expiringTu certificado digital está por vencer.
certificate.expiredTu certificado digital venció.
dgii.service_degradedLa 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_restoredLa DGII volvió a responder en ese ambiente. data trae state: "restored", since y degradedSince.
dgii.service_slowLa 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_clearedLa DGII vuelve a resolver los e-CF a tiempo en ese ambiente. data trae state: "normal", since y slowSince.
webhook.testLo 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.status es 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, trae printing, con lo necesario para la representación impresa. Antes es null y printingStatus dice por qué (awaiting_signature, awaiting_dgii o rejected).
  • document.printing.legends trae las leyendas que lleva el PDF, con su texto literal, y document.contingency.startedAt dice desde cuándo el envío se difirió por contingencia (null si nunca se difirió). Ambos se mantienen en los eventos siguientes, aunque el documento quede accepted. Ver Leyendas.
  • document.printing.pdfUrl es la descarga del PDF de la representación impresa por API, con tu API key (ecf:read), igual que GET /{ambiente}/documentos-ecf/{documentId}/pdf. Viene solo cuando la RI ya se entrega.
  • document.lastError dice por qué el documento no avanza (por ejemplo DGII_CERTIFICATE_NOT_DELEGATED, con hint), con los mismos campos que la consulta por lote, incluido retrying. Es null sin error o con estado final. Cuando aparece un código nuevo recibes un document.state_changed una vez, aunque status no haya cambiado.
  • Un document.state_changed con status: transmission_failed (y lastError.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 trae printing (su representación impresa no se entrega).
  • document.received trae data.inboundDocumentId, data.encf y data.xmlUrl: la descarga del XML del proveedor con tu X-API-KEY (ecf:read), para registrar la compra.
  • document.commercial_approval_received trae data.inboundDocumentId, data.encf (tu e-CF), data.status (accepted o rejected), data.rejectionReason, data.buyerRnc y data.correspondence: si el ACECF corresponde con tu e-CF emitido (status matched, mismatch con los campos que difieren en mismatches, o ecf_not_found), igual que en la lista de aprobaciones recibidas. Con el inboundDocumentId consultas el ACECF y descargas su XML en GET /{ambiente}/aprobaciones-comerciales-recibidas/{inboundDocumentId}.
  • document.commercial_approval_due trae data.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) y data.daysRemaining (días que faltan, en hora de República Dominicana).
  • annulment.state_changed trae data.annulmentId, data.status (accepted, rejected, failed o uncertain), data.totalAnnulled y data.dgiiCode.
  • certificate.expiring y certificate.expired traen data.validTo y data.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 v1 mientras conviven el secreto anterior y el nuevo: acepta la entrega si cualquiera coincide. No conviertas la cabecera con Object.fromEntries ni con un mapa clave→valor, porque te quedarías solo con el último v1.
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-Id con una restricción única antes de aplicar cambios. Si ya lo procesaste, responde 200 sin 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 receptorQué hace ZarelaFact
Cualquier 2xxEntrega exitosa.
Error de red, timeout (10 s), 408, 429 o 5xxReintenta con espera creciente, hasta 8 intentos en total.
3xx u otro 4xxMarca 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 v1 en Zarela-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.