Webhooks
Recibe notificaciones en tiempo real sobre el estado de tus facturas con los webhooks de QAPI.
Los webhooks de QAPI te permiten recibir notificaciones automáticas cuando el estado de una factura cambia — sin hacer polling.
Eventos disponibles
| Evento | Cuándo se dispara |
|---|---|
invoice.certified | La factura fue certificada ante la SAT |
invoice.failed | La certificación falló (firma o certificación) |
invoice.cancelled | La factura fue anulada |
invoice.test | Disparado manualmente desde el dashboard (botón "Probar webhook") con datos de ejemplo fijos |
quota.threshold_reached | Tu cuenta llegó al 80% o al 100% del saldo de DTEs del mes. Ver Aviso de consumo |
Las pruebas también disparan webhooks — distinguilas con data.test
Las emisiones de prueba (certificador MOCK) sí disparan webhooks: tanto las de
POST /v1/sandbox/invoices como cualquier emisión de una cuenta aún sin certificador real.
Todas llevan data.test: true. Las emisiones reales llevan data.test: false. Usá ese campo
para no confundir una notificación de prueba con una factura con validez fiscal.
POST /v1/sandbox/invoices usa tu webhook global (el de la cuenta) o el webhook_url que
envíes en el body, firmado con el secret de la cuenta.
Configuración
QAPI resuelve qué webhook usar en este orden — el primero que exista gana:
- Por request (
webhook_urlen el body dePOST /v1/invoices) — solo esa factura. Se firma con el secret del webhook del proyecto o, si el proyecto no tiene, con el de la cuenta. - Por proyecto — cada proyecto puede tener su propia URL y secret HMAC. Útil si cada cliente final quiere sus notificaciones en su propio sistema. Ver Proyectos.
- De la cuenta — el webhook global, usado cuando la factura no vino de un proyecto con
webhook propio ni trajo
webhook_urlen el request.
1. Por request
{
"tipo_dte": "FACT",
"webhook_url": "https://tu-sistema.com/webhooks/qapi",
...
}El webhook por request necesita un secret configurado
QAPI no inventa un secret para esa URL: firma con el del proyecto o con el de la cuenta. Si ninguno de los dos tiene webhook configurado, la factura se emite igual pero la entrega no se hace. Configurá al menos el webhook de la cuenta para tener un secret con qué verificar.
2. Por proyecto
Se configura al editar el proyecto en el dashboard. El secret se muestra una sola vez al generarlo o rotarlo — a diferencia de la API key, no es recuperable después.
3. De la cuenta (global)
Se configura en el dashboard, en Webhooks. El secret también se muestra solo al generarlo o rotarlo: guardalo en ese momento.
Estructura del payload
Todos los eventos siguen la misma estructura:
Propiedad
Tipo
data.test — distingue prueba de emisión real
data.test es true cuando el documento se emitió con el certificador MOCK (sandbox o cuenta
sin activar): no tiene validez fiscal. En emisiones reales es false. Está presente en
invoice.certified, invoice.failed e invoice.cancelled.
invoice.test tiene una forma distinta
El evento invoice.test (botón "Probar webhook" del dashboard) no sigue la misma forma:
agrega un timestamp en la raíz, su data no trae test ni pdf_url (trae gran_total y un
_note aclarando que es de prueba) y los valores son fijos (id: "inv_test_000000000000", etc).
Es solo para confirmar que tu endpoint recibe y verifica la firma — no lo uses como referencia
de la forma real de invoice.certified.
El campo del UUID se llama uuid (no uuid_sat)
En el payload del webhook el identificador SAT viaja como data.uuid. El nombre uuid_sat
solo se usa en las respuestas de la API REST (GET /v1/invoices/:id).
Headers de cada entrega
| Header | Valor |
|---|---|
X-QAPI-Signature-V2 | sha256=<hmac-hex> — firma HMAC-SHA256 de <id>.<timestamp>.<body> con tu webhook secret. La recomendada |
X-QAPI-Webhook-Id | Id de la entrega (whk_…). Es el mismo en los reintentos de esa entrega |
X-QAPI-Timestamp | Momento del envío, en segundos Unix |
X-QAPI-Signature | sha256=<hmac-hex> — firma HMAC-SHA256 del body solo. Se mantiene por compatibilidad |
X-QAPI-Event | El tipo de evento (ej. invoice.certified) |
User-Agent | QAPI-Webhook/1.0 |
Ejemplo — invoice.certified
{
"event": "invoice.certified",
"data": {
"id": "inv_V1StGXR8_Z5jdHi6",
"status": "CERTIFIED",
"test": false,
"uuid": "550E8400-E29B-41D4-A716-446655440000",
"serie": "A",
"numero_dte": 42,
"pdf_url": "https://print.totaldoc.io/pdf?uuid=550E8400...",
"certified_at": "2026-06-08T16:00:02.000Z"
}
}Ejemplo — invoice.failed
{
"event": "invoice.failed",
"data": {
"id": "inv_V1StGXR8_Z5jdHi6",
"status": "FAILED",
"test": false,
"error_code": "CERT_FAILED",
"error_message": "Regla SAT 2.2.4.4: El NIT del Receptor es inválido"
}
}En los rechazos de la certificación (CERT_FAILED), error_message arranca con
Regla SAT <código> — el código de la regla de la SAT que no se cumplió, explicado en
Reglas SAT. Ver
Estados de Factura.
Aviso de consumo (quota.threshold_reached)
El mismo aviso que te llega por correo al 80% y al 100% del saldo del mes, para que lo integres en tu sistema: avisarle a tu cliente, frenar emisiones no urgentes o activar los excedentes.
- Llega al webhook de la cuenta (el global), no al de un proyecto: el saldo es del plan.
- Se envía una sola vez por nivel en cada mes. Si la cuenta pasa del 79% al 100% de golpe, llega solo el del 100%.
- Puede llegar hasta unos minutos después de la emisión que cruzó el nivel.
data.ides estable por mes y nivel (quota_2026-10_80), yX-QAPI-Webhook-Idtambién: si te llega dos veces, es el mismo aviso.
{
"event": "quota.threshold_reached",
"data": {
"id": "quota_2026-10_80",
"level": 80,
"period": "2026-10",
"used": 82,
"limit": 100,
"overage_enabled": false,
"overage_cap": 500
}
}| Campo | Qué es |
|---|---|
level | 80 o 100 |
period | Mes del consumo, en hora de Guatemala (YYYY-MM) |
used | DTEs consumidos en el mes: emisiones y anulaciones reales (las pruebas y los intentos fallidos no cuentan) |
limit | Saldo de DTEs del mes de tu cuenta |
overage_enabled | Si tenés los excedentes activados |
overage_cap | Máximo de DTEs del mes contando los excedentes |
Se firma igual que los eventos de facturas: verificá X-QAPI-Signature-V2 como se explica abajo.
Implementar el endpoint receptor
Responder 200 rápidamente
QAPI espera una respuesta 2xx en menos de 10 segundos. Si tu servidor tarda más,
QAPI marcará la entrega como fallida y reintentará.
El body de la respuesta es ignorado — solo importa el código HTTP.
import express from 'express';
const app = express();
app.use(express.json());
app.post('/webhooks/qapi', async (req, res) => {
// Responde 200 INMEDIATAMENTE antes de procesar
res.sendStatus(200);
const { event, data } = req.body;
// Procesa de forma asíncrona
setImmediate(() => handleQapiEvent(event, data));
});from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel
app = FastAPI()
class WebhookPayload(BaseModel):
event: str
data: dict
@app.post("/webhooks/qapi")
async def qapi_webhook(payload: WebhookPayload, background_tasks: BackgroundTasks):
# Responde 200 inmediatamente
background_tasks.add_task(handle_qapi_event, payload.event, payload.data)
return {"ok": True}Verificar la firma — siempre
QAPI firma todas las entregas con HMAC-SHA256; eso no es opcional de nuestro lado. Lo que
depende de vos es verificarla, y no deberías saltearte ese paso: tu endpoint es una URL
pública, y sin verificar la firma cualquiera que la descubra puede mandarle un invoice.certified
falso y hacerle creer a tu sistema que una factura se certificó cuando no fue así.
Verificá X-QAPI-Signature-V2. Firma el body junto con el id y el momento del envío, así
que además de confirmar que el mensaje es nuestro te deja rechazar uno viejo que alguien
capturó y vuelve a mandar:
- Armá
<X-QAPI-Webhook-Id>.<X-QAPI-Timestamp>.<raw body>y calculá su HMAC-SHA256 con tu webhook secret. - Compará con el header en tiempo constante.
- Rechazá la entrega si el timestamp tiene más de 5 minutos de diferencia con tu reloj.
import crypto from 'crypto';
const TOLERANCIA_SEGUNDOS = 5 * 60;
function verifySignature(
rawBody: string,
headers: Record<string, string | undefined>,
secret: string
): boolean {
const id = headers['x-qapi-webhook-id'];
const timestamp = headers['x-qapi-timestamp'];
const signature = headers['x-qapi-signature-v2'];
if (!id || !timestamp || !signature) return false;
// Entrega vieja: aunque la firma sea válida, es un reenvío.
const ts = Number(timestamp);
if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > TOLERANCIA_SEGUNDOS) return false;
const expected = `sha256=${crypto
.createHmac('sha256', secret)
.update(`${id}.${timestamp}.${rawBody}`)
.digest('hex')}`;
const a = Buffer.from(expected);
const b = Buffer.from(signature);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post('/webhooks/qapi', express.raw({ type: 'application/json' }), (req, res) => {
const rawBody = req.body.toString();
if (!verifySignature(rawBody, req.headers as Record<string, string>, process.env.QAPI_WEBHOOK_SECRET!)) {
return res.status(401).json({ error: 'Firma inválida' });
}
res.sendStatus(200);
const payload = JSON.parse(rawBody);
setImmediate(() => handleQapiEvent(payload));
});Calculá la firma sobre el body crudo, tal como llegó. Si tu framework ya lo parseó a JSON y lo volvés a serializar, el orden o los espacios pueden cambiar y la firma no va a coincidir.
X-QAPI-Signature (la firma del body solo) se sigue enviando para no romper integraciones
existentes, pero no protege contra reenvíos. Si tu endpoint la usa, pasate a la V2.
Deduplicar por factura + evento
QAPI puede reenviar un evento si tu endpoint no respondió 2xx a tiempo. Usá la combinación
data.id + event como clave de deduplicación (cada factura emite cada evento una sola vez).
X-QAPI-Webhook-Id se repite en los reintentos de una misma entrega, pero no reemplaza a esta
clave: si el evento se vuelve a despachar más tarde, llega con un id nuevo.
const processed = new Set<string>();
async function handleQapiEvent(payload: any) {
const dedupKey = `${payload.data.id}:${payload.event}`;
if (processed.has(dedupKey)) {
console.log(`Evento duplicado ignorado: ${dedupKey}`);
return;
}
processed.add(dedupKey);
switch (payload.event) {
case 'invoice.certified':
await markInvoiceCertified(payload.data.id, payload.data.uuid);
break;
case 'invoice.failed':
await notifyFailure(payload.data.id, payload.data.error_message);
break;
}
}En producción usa Redis o una tabla de base de datos en lugar de un Set en memoria.
Reintentos
Si tu endpoint no responde 2xx, QAPI hace hasta 3 intentos en total con backoff corto:
| Intento | Espera previa |
|---|---|
| 1 | inmediato |
| 2 | 1 segundo |
| 3 | 3 segundos |
Es decir, dos reintentos tras el primer envío, separados 1 s y 3 s. Después del tercer intento
fallido la entrega se abandona — no hay reintentos horas después. Si tu sistema estuvo caído,
recupera el estado con polling:
GET /v1/invoices?status=CERTIFIED o GET /v1/invoices/:id.
Diseña tu receptor asumiendo entregas perdidas
El webhook es una optimización para evitar polling constante, no un canal garantizado.
La fuente de verdad del estado de una factura es siempre GET /v1/invoices/:id.
Restricciones de la URL del webhook
- Debe ser HTTPS —
http://se rechaza (en elwebhook_urlde una factura, conSSRF_BLOCKED). - Debe ser una URL pública. Una que apunte a una red privada o interna (
localhost,192.168.x.x, o un dominio que resuelva a una de esas direcciones) se rechaza conSSRF_BLOCKEDal guardarla en el dashboard o al mandarla en elwebhook_urldel body de una factura. Para probar en local, exponé tu endpoint con un túnel HTTPS público. - Debe usar el puerto 443, el de HTTPS. Una URL con otro puerto
(
https://tu-sistema.com:8443/...) se rechaza conVALIDATION_ERROR. - No puede llevar usuario ni contraseña (
https://usuario:clave@tu-sistema.com/...): se rechaza conVALIDATION_ERROR. Para saber que el evento viene de QAPI, verificá la firma. - QAPI no sigue redirects: si tu endpoint responde
301/302, la entrega cuenta como fallida. - Tu endpoint debe responder en menos de 10 segundos.