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.
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
| Evento | Cuándo se envía |
|---|---|
document.queued | El comprobante fue recibido y puesto en cola. |
document.invalid | El comprobante no superó la validación previa. |
document.accepted | La DGII aceptó el comprobante. |
document.accepted_conditional | La DGII aceptó el comprobante con observaciones. |
document.rejected | La DGII rechazó el comprobante. |
document.delivery.acknowledged | El receptor acusó recibo del comprobante. |
document.delivery.failed | No se pudo entregar el comprobante al receptor. |
document.commercial.approved | El receptor aprobó comercialmente el comprobante. |
document.commercial.rejected | El receptor rechazó comercialmente el comprobante. |
received_document.created | Tu empresa recibió un e-CF de un proveedor. |
cancellation.completed | Se completó una anulación de secuencias. |
dgii.status_changed | Cambió el estado de disponibilidad de los servicios de la DGII. |
contingency.started | La plataforma entró en contingencia. |
contingency.ended | Terminó la contingencia. |
certificate.expiring | El certificado digital de una empresa está por vencer. |
certificate.expired | El certificado digital de una empresa venció. |
Formato de la entrega
Cada evento llega como una solicitud POST con cuerpo JSON y tres encabezados:
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);
import { createHmac, timingSafeEqual } from 'node:crypto';
function verificar(rawBody, headers, secreto) {
const contenido = `${headers['webhook-id']}.${headers['webhook-timestamp']}.${rawBody}`;
const esperada = createHmac('sha256', secreto).update(contenido).digest('base64');
const recibida = headers['webhook-signature'].replace(/^v1,/, '');
const a = Buffer.from(esperada);
const b = Buffer.from(recibida);
return a.length === b.length && timingSafeEqual(a, b);
}
function verificar(string $rawBody, array $headers, string $secreto): bool
{
$contenido = $headers['webhook-id'].'.'.$headers['webhook-timestamp'].'.'.$rawBody;
$esperada = base64_encode(hash_hmac('sha256', $contenido, $secreto, true));
$recibida = preg_replace('/^v1,/', '', $headers['webhook-signature']);
return hash_equals($esperada, $recibida);
}
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
2xxen 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-idpara descartar duplicados.
Probar y reenviar
POST /v1/webhook-endpoints/{id}/testenvía un evento de prueba a tu endpoint.GET /v1/webhook-deliverieslista las entregas con su resultado.POST /v1/webhook-deliveries/{id}/redeliverreenvía una entrega concreta.
¿Algo no está claro o falta en esta página? Escríbenos por el centro de soporte.