DEVSDESIGN — DEVELOPERS & DESIGN

API v1 · contrato 1.0.0

Webhooks

Eventos disponibles, verificación de firma y política de reintentos.

Los webhooks avisan a tu sistema cuando algo cambia, sin que tengas que consultar el estado una y otra vez. Son la forma recomendada de conocer el resultado de un comprobante.

Registrar un endpoint

Requiere el permiso webhooks:manage. Indica la URL que recibirá los eventos y cuáles quieres recibir. Con company_ids puedes limitar el endpoint a ciertas empresas emisoras.

POST /v1/webhook-endpoints
curl https://api.devsdesign.cloud/v1/webhook-endpoints \
  -H "Authorization: Bearer $DD_API_KEY" \
  -H "Idempotency-Key: webhook-principal" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-sistema.example/webhooks/ecf",
    "events": ["document.accepted", "document.rejected", "document.invalid"]
  }'

La respuesta incluye el secreto del endpoint (empieza por whsec_). Guárdalo: lo necesitas para verificar las firmas.

Eventos disponibles

EventoCuándo se envía
document.queuedEl comprobante fue recibido y puesto en cola.
document.invalidEl comprobante no superó la validación previa.
document.acceptedLa DGII aceptó el comprobante.
document.accepted_conditionalLa DGII aceptó el comprobante con observaciones.
document.rejectedLa DGII rechazó el comprobante.
document.delivery.acknowledgedEl receptor acusó recibo del comprobante.
document.delivery.failedNo se pudo entregar el comprobante al receptor.
document.commercial.approvedEl receptor aprobó comercialmente el comprobante.
document.commercial.rejectedEl receptor rechazó comercialmente el comprobante.
received_document.createdTu empresa recibió un e-CF de un proveedor.
cancellation.completedSe completó una anulación de secuencias.
dgii.status_changedCambió el estado de disponibilidad de los servicios de la DGII.
contingency.startedLa plataforma entró en contingencia.
contingency.endedTerminó la contingencia.
certificate.expiringEl certificado digital de una empresa está por vencer.
certificate.expiredEl certificado digital de una empresa venció.

Formato de la entrega

Cada evento llega como una solicitud POST con cuerpo JSON y tres encabezados:

Entrega de un webhook
POST /webhooks/ecf
webhook-id: evt_…
webhook-timestamp: 1794836963
webhook-signature: v1,K8mZ…=

{
  "type": "document.accepted",
  "data": { … }
}

El contenido de data depende del evento. Los valores del ejemplo son ilustrativos.

Verificar la firma

Verifica siempre la firma antes de confiar en un evento. Se calcula como un HMAC-SHA256, codificado en base64, sobre la cadena {webhook-id}.{webhook-timestamp}.{cuerpo}, usando el secreto del endpoint.

import { Webhook } from '@devsdesign/ecf';

// rawBody debe ser el cuerpo tal como llegó, sin volver a serializarlo
Webhook.verify(rawBody, request.headers, process.env.DD_WEBHOOK_SECRET);

Compara también webhook-timestamp con la hora actual y descarta eventos demasiado antiguos. Así evitas que alguien reenvíe una entrega capturada.

Respuesta y reintentos

  • Responde con un código 2xx en menos de 10 segundos. Procesa el evento después de responder si tu lógica es lenta.
  • Si tu endpoint falla o no responde a tiempo, la entrega se reintenta con esperas crecientes, hasta 10 intentos.
  • Agotados los reintentos, el endpoint se desactiva. Puedes reactivarlo con PATCH /v1/webhook-endpoints/{id}.
  • Un mismo evento puede llegar más de una vez. Usa webhook-id para descartar duplicados.

Probar y reenviar

  • POST /v1/webhook-endpoints/{id}/test envía un evento de prueba a tu endpoint.
  • GET /v1/webhook-deliveries lista las entregas con su resultado.
  • POST /v1/webhook-deliveries/{id}/redeliver reenvía una entrega concreta.

¿Algo no está claro o falta en esta página? Escríbenos por el centro de soporte.