Cómo funcionan los webhooks
En lugar de consultar GET /v1/documents/{id} hasta que SUNAT responda, registra una URL y Faktura te avisa con un POST firmado cada vez que un comprobante llega a un desenlace.
Eventos
Sección titulada «Eventos»| Evento | Cuándo |
|---|---|
document.accepted |
SUNAT aceptó el comprobante. |
document.observed |
SUNAT lo aceptó con observaciones. |
document.rejected |
SUNAT lo rechazó. |
document.failed |
No se pudo procesar (credenciales, perfil SOL…). |
document.voided |
SUNAT aceptó la anulación. |
document.void_rejected |
SUNAT rechazó la anulación; el comprobante sigue vigente. |
Cómo empezar
Sección titulada «Cómo empezar»- Registra tu endpoint y guarda el
secret. - Verifica la firma de cada aviso (abajo) y responde
2xxen menos de 10 segundos. - Lista o elimina endpoints cuando lo necesites (hasta 10 por empresa).
La petición que recibes
Sección titulada «La petición que recibes»POST /faktura/webhook HTTP/1.1Content-Type: application/jsonUser-Agent: Faktura-Webhooks/1Faktura-Event: document.acceptedFaktura-Event-Id: 01a1d6b3-0b7a-7d11-8e40-3a2f1c9d8e77Faktura-Delivery: 01a1d6b3-0c11-72c5-a0f4-6b1e2d3c4f55Faktura-Signature: t=1794600000,v1=5d41402abc4b2a76b9719d911017c592…
{ "id": "01a1d6b3-0b7a-7d11-8e40-3a2f1c9d8e77", "type": "document.accepted", "created_at": "2026-11-13T22:00:01+00:00", "data": { "document_id": "01a1d5fc-899b-720e-a6ea-03d37a346f81", "document_type": "03", "full_number": "B001-1", "environment": "beta", "status": "accepted", "sunat_code": "0", "sunat_description": "La Boleta numero B001-1, ha sido aceptada", "void_status": null }}Responde con cualquier 2xx en menos de 10 segundos. Haz el trabajo pesado después: guarda el evento y procésalo en segundo plano.
Verificar la firma
Sección titulada «Verificar la firma»Faktura-Signature contiene t (marca de tiempo Unix) y v1 (HMAC-SHA256 en hexadecimal de "<t>.<cuerpo>" con tu secret). Verifica siempre sobre el cuerpo crudo, antes de convertirlo a JSON, y rechaza marcas de tiempo de más de 5 minutos para impedir repeticiones.
PHP:
$body = file_get_contents('php://input');preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $_SERVER['HTTP_FAKTURA_SIGNATURE'] ?? '', $m);$valid = $m && abs(time() - (int) $m[1]) <= 300 && hash_equals(hash_hmac('sha256', $m[1].'.'.$body, getenv('FAKTURA_WEBHOOK_SECRET')), $m[2]);if (! $valid) { http_response_code(400); exit; }Node.js (Express):
import crypto from 'node:crypto';
app.post('/faktura/webhook', express.raw({ type: 'application/json' }), (req, res) => { const [, t, v1] = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(req.get('Faktura-Signature') ?? '') ?? []; const expected = crypto.createHmac('sha256', process.env.FAKTURA_WEBHOOK_SECRET) .update(`${t}.${req.body}`).digest('hex'); const valid = t && Math.abs(Date.now() / 1000 - Number(t)) <= 300 && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)); if (!valid) return res.sendStatus(400); res.sendStatus(204); // procesar JSON.parse(req.body) en segundo plano});Reintentos y duplicados
Sección titulada «Reintentos y duplicados»- Si tu endpoint no responde
2xx(error, timeout o redirección, que no se sigue), Faktura reintenta con espera creciente: 5 s, 10 s, 20 s… hasta 15 minutos entre intentos, durante unas 4 horas. - La entrega es al menos una vez: puedes recibir el mismo evento más de una vez. Usa
id(igual aFaktura-Event-Id) para ignorar duplicados. - El orden de llegada no está garantizado. Si dudas, consulta
GET /v1/documents/{id}, que siempre tiene el estado vigente.