QAPI está en beta — la API puede cambiar sin previo aviso. Usá sandbox para pruebas.
QAPIQAPIDocs · by DTEVIA
Guías

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

EventoCuándo se dispara
invoice.certifiedLa factura fue certificada ante la SAT
invoice.failedLa certificación falló (firma o certificación)
invoice.cancelledLa factura fue anulada
invoice.testDisparado manualmente desde el dashboard (botón "Probar webhook") con datos de ejemplo fijos
quota.threshold_reachedTu 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:

  1. Por request (webhook_url en el body de POST /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.
  2. 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.
  3. De la cuenta — el webhook global, usado cuando la factura no vino de un proyecto con webhook propio ni trajo webhook_url en 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

HeaderValor
X-QAPI-Signature-V2sha256=<hmac-hex> — firma HMAC-SHA256 de <id>.<timestamp>.<body> con tu webhook secret. La recomendada
X-QAPI-Webhook-IdId de la entrega (whk_…). Es el mismo en los reintentos de esa entrega
X-QAPI-TimestampMomento del envío, en segundos Unix
X-QAPI-Signaturesha256=<hmac-hex> — firma HMAC-SHA256 del body solo. Se mantiene por compatibilidad
X-QAPI-EventEl tipo de evento (ej. invoice.certified)
User-AgentQAPI-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.id es estable por mes y nivel (quota_2026-10_80), y X-QAPI-Webhook-Id tambié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
  }
}
CampoQué es
level80 o 100
periodMes del consumo, en hora de Guatemala (YYYY-MM)
usedDTEs consumidos en el mes: emisiones y anulaciones reales (las pruebas y los intentos fallidos no cuentan)
limitSaldo de DTEs del mes de tu cuenta
overage_enabledSi tenés los excedentes activados
overage_capMá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:

  1. Armá <X-QAPI-Webhook-Id>.<X-QAPI-Timestamp>.<raw body> y calculá su HMAC-SHA256 con tu webhook secret.
  2. Compará con el header en tiempo constante.
  3. 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:

IntentoEspera previa
1inmediato
21 segundo
33 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 el webhook_url de una factura, con SSRF_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 con SSRF_BLOCKED al guardarla en el dashboard o al mandarla en el webhook_url del 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 con VALIDATION_ERROR.
  • No puede llevar usuario ni contraseña (https://usuario:clave@tu-sistema.com/...): se rechaza con VALIDATION_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.

En esta página