Ir al contenido

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.

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.
  1. Registra tu endpoint y guarda el secret.
  2. Verifica la firma de cada aviso (abajo) y responde 2xx en menos de 10 segundos.
  3. Lista o elimina endpoints cuando lo necesites (hasta 10 por empresa).
POST /faktura/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Faktura-Webhooks/1
Faktura-Event: document.accepted
Faktura-Event-Id: 01a1d6b3-0b7a-7d11-8e40-3a2f1c9d8e77
Faktura-Delivery: 01a1d6b3-0c11-72c5-a0f4-6b1e2d3c4f55
Faktura-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.

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
});
  • 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 a Faktura-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.