Webhooks
Tezora notifica a una dirección de la empresa cada cambio de estado del documento de una venta creada por la API. Los destinos se registran en el menú Empresa > Configuración, pestaña Integraciones: una dirección https pública en el puerto 443, sin usuario ni contraseña (no se aceptan redes privadas ni direcciones que apunten a ellas) y los eventos suscritos. Cada destino tiene un secreto whsec_… que se muestra una vez. El evento ping solo se envía con el botón Enviar prueba.
El cuerpo de cada evento está en Eventos y refleja el estado en el momento del hecho. data.sale es la venta tal como la da GET /sales/{uuid}, con branch (uuid, name y code, el codEstable del documento) y point_of_sale (uuid, name y code, el codPuntoVenta): un mismo destino recibe los eventos de todas las sucursales de la empresa y los separa por esos campos. En los eventos de notas, uuid y reference de adjustment_note son los mismos que la nota tiene en adjustment_notes de GET /sales/{uuid}, desde el primer evento. Las cabeceras son Tezora-Signature, Tezora-Event, Tezora-Delivery y User-Agent: Tezora-Webhooks/2. Un evento puede llegar más de una vez y se deduplica por id, que es el mismo en todos los destinos.
Una entrega es exitosa con cualquier respuesta 2xx dentro de 10 segundos; las redirecciones no se siguen. Una entrega fallida se reintenta hasta 6 veces en total, a 1 minuto, 5 minutos, 30 minutos, 2 horas y 6 horas. Tras 20 fallas seguidas el destino se desactiva y la administración de la empresa recibe un correo; se reactiva desde la misma pantalla, que también muestra el historial y permite el reenvío manual.
sequenceDiagram
participant T as Tezora
participant R as Receptor
T->>R: POST con Tezora-Signature
R->>R: Verificar la firma sobre el cuerpo crudo
alt Firma válida
R-->>T: 2xx en menos de 10 s
else Sin respuesta o error
T->>R: Reintentos a 1 min, 5 min, 30 min, 2 h y 6 h
end
Verificar la firma
Tezora-Signature: t=<segundos unix>,sha256=<hex>
sha256 es el HMAC-SHA256 en hexadecimal de <t>.<cuerpo crudo>, con el secreto del destino como clave. Durante las 24 horas siguientes a una rotación del secreto, la cabecera lleva una segunda firma, la del secreto anterior:
Tezora-Signature: t=<segundos unix>,sha256=<hex con el secreto nuevo>,sha256=<hex con el secreto anterior>
- Leer el cuerpo crudo, antes de decodificar el JSON.
- Separar
ty cada valorsha256. - Rechazar si
tdifiere en más de 5 minutos de la hora actual. - Calcular el HMAC de
t + "." + cuerpoy compararlo en tiempo constante con cadasha256. Basta una coincidencia.
Los ejemplos usan el secreto whsec_ejemplo_no_usar, t igual a 1761000000 y el cuerpo de los ejemplos. La firma esperada es:
aee4a13236c726b4284f413dd33c38823f4bab98a4c5e67a1c1338e0c3af0bf5
PHP
<?php
function tezoraSignatureIsValid(string $secret, string $rawBody, string $header, ?int $now = null, int $tolerance = 300): bool
{
if (preg_match('/^t=(\d+)((?:,sha256=[0-9a-f]{64})+)$/', $header, $parts) !== 1) {
return false;
}
if (abs(($now ?? time()) - (int) $parts[1]) > $tolerance) {
return false;
}
$expected = hash_hmac('sha256', $parts[1].'.'.$rawBody, $secret);
$matched = false;
foreach (explode(',sha256=', substr($parts[2], strlen(',sha256='))) as $signature) {
$matched = hash_equals($expected, $signature) || $matched;
}
return $matched;
}
// $rawBody = file_get_contents('php://input');
// $header = $_SERVER['HTTP_TEZORA_SIGNATURE'] ?? '';
$body = '{"id":"3f6c1a52-8e1d-4b7a-9d0e-5a2c7b9f1e44","type":"sale.document.processed","created_at":"2026-10-23T10:15:00-06:00","data":{}}';
echo hash_hmac('sha256', '1761000000.'.$body, 'whsec_ejemplo_no_usar'), "\n";
Node.js
const crypto = require('node:crypto');
function tezoraSignatureIsValid(secret, rawBody, header, now = Math.floor(Date.now() / 1000), tolerance = 300) {
const match = /^t=(\d+)((?:,sha256=[0-9a-f]{64})+)$/.exec(header);
if (!match) return false;
if (Math.abs(now - Number(match[1])) > tolerance) return false;
const expected = Buffer.from(crypto.createHmac('sha256', secret).update(`${match[1]}.${rawBody}`).digest('hex'));
const signatures = match[2].slice(',sha256='.length).split(',sha256=');
return signatures.reduce((found, signature) => crypto.timingSafeEqual(expected, Buffer.from(signature)) || found, false);
}
// En Express: express.raw({ type: 'application/json' }) y req.body.toString('utf8') como rawBody.
const body = '{"id":"3f6c1a52-8e1d-4b7a-9d0e-5a2c7b9f1e44","type":"sale.document.processed","created_at":"2026-10-23T10:15:00-06:00","data":{}}';
console.log(crypto.createHmac('sha256', 'whsec_ejemplo_no_usar').update(`1761000000.${body}`).digest('hex'));
Python
import hashlib
import hmac
import re
import time
def tezora_signature_is_valid(secret: str, raw_body: bytes, header: str, now: int | None = None, tolerance: int = 300) -> bool:
match = re.fullmatch(r"t=(\d+)((?:,sha256=[0-9a-f]{64})+)", header)
if not match:
return False
if abs((now if now is not None else int(time.time())) - int(match.group(1))) > tolerance:
return False
expected = hmac.new(secret.encode(), match.group(1).encode() + b"." + raw_body, hashlib.sha256).hexdigest()
signatures = match.group(2)[len(",sha256="):].split(",sha256=")
return any([hmac.compare_digest(expected, signature) for signature in signatures])
# En Flask: raw_body = request.get_data(); header = request.headers["Tezora-Signature"]
body = b'{"id":"3f6c1a52-8e1d-4b7a-9d0e-5a2c7b9f1e44","type":"sale.document.processed","created_at":"2026-10-23T10:15:00-06:00","data":{}}'
print(hmac.new(b"whsec_ejemplo_no_usar", b"1761000000." + body, hashlib.sha256).hexdigest())
La rotación del secreto no interrumpe al receptor: durante 24 horas cada entrega lleva las firmas del secreto nuevo y del anterior, y el verificador acepta cualquiera. Una segunda rotación dentro de esa ventana invalida el secreto más antiguo.
Eventos
sale.document.processed
Hacienda procesó el documento de una venta creada por la API.
| Campo | Tipo | Descripción |
|---|---|---|
id |
string (uuid) | Identificador del evento, igual en todos los destinos y reintentos. |
type |
string | Tipo del evento, igual a la cabecera Tezora-Event. |
created_at |
string (date-time) | Momento del hecho, con el desfase de El Salvador. |
data |
object | Objeto del evento, tal como estaba en ese momento. |
data.sale |
SaleResource |
sale.document.rejected
Hacienda rechazó el documento de una venta creada por la API.
| Campo | Tipo | Descripción |
|---|---|---|
id |
string (uuid) | Identificador del evento, igual en todos los destinos y reintentos. |
type |
string | Tipo del evento, igual a la cabecera Tezora-Event. |
created_at |
string (date-time) | Momento del hecho, con el desfase de El Salvador. |
data |
object | Objeto del evento, tal como estaba en ese momento. |
data.sale |
SaleResource |
sale.document.contingency
El documento de una venta creada por la API quedó en contingencia.
| Campo | Tipo | Descripción |
|---|---|---|
id |
string (uuid) | Identificador del evento, igual en todos los destinos y reintentos. |
type |
string | Tipo del evento, igual a la cabecera Tezora-Event. |
created_at |
string (date-time) | Momento del hecho, con el desfase de El Salvador. |
data |
object | Objeto del evento, tal como estaba en ese momento. |
data.sale |
SaleResource |
sale.document.invalidated
El documento de una venta creada por la API fue invalidado.
| Campo | Tipo | Descripción |
|---|---|---|
id |
string (uuid) | Identificador del evento, igual en todos los destinos y reintentos. |
type |
string | Tipo del evento, igual a la cabecera Tezora-Event. |
created_at |
string (date-time) | Momento del hecho, con el desfase de El Salvador. |
data |
object | Objeto del evento, tal como estaba en ese momento. |
data.sale |
SaleResource |
sale.adjustment_note.processed
Hacienda procesó una nota de crédito o de débito de una venta creada por la API.
| Campo | Tipo | Descripción |
|---|---|---|
id |
string (uuid) | Identificador del evento, igual en todos los destinos y reintentos. |
type |
string | Tipo del evento, igual a la cabecera Tezora-Event. |
created_at |
string (date-time) | Momento del hecho, con el desfase de El Salvador. |
data |
object | Objeto del evento, tal como estaba en ese momento. |
data.adjustment_note |
WebhookAdjustmentNoteResource | |
data.sale |
SaleResource |
sale.adjustment_note.contingency
Una nota de crédito o de débito de una venta creada por la API pasó a contingencia.
| Campo | Tipo | Descripción |
|---|---|---|
id |
string (uuid) | Identificador del evento, igual en todos los destinos y reintentos. |
type |
string | Tipo del evento, igual a la cabecera Tezora-Event. |
created_at |
string (date-time) | Momento del hecho, con el desfase de El Salvador. |
data |
object | Objeto del evento, tal como estaba en ese momento. |
data.adjustment_note |
WebhookAdjustmentNoteResource | |
data.sale |
SaleResource |
sale.adjustment_note.rejected
Hacienda rechazó una nota de crédito o de débito de una venta creada por la API.
| Campo | Tipo | Descripción |
|---|---|---|
id |
string (uuid) | Identificador del evento, igual en todos los destinos y reintentos. |
type |
string | Tipo del evento, igual a la cabecera Tezora-Event. |
created_at |
string (date-time) | Momento del hecho, con el desfase de El Salvador. |
data |
object | Objeto del evento, tal como estaba en ese momento. |
data.adjustment_note |
WebhookAdjustmentNoteResource | |
data.sale |
SaleResource |
sale.adjustment_note.invalidated
Hacienda aceptó la invalidación de una nota de crédito o de débito de una venta creada por la API.
| Campo | Tipo | Descripción |
|---|---|---|
id |
string (uuid) | Identificador del evento, igual en todos los destinos y reintentos. |
type |
string | Tipo del evento, igual a la cabecera Tezora-Event. |
created_at |
string (date-time) | Momento del hecho, con el desfase de El Salvador. |
data |
object | Objeto del evento, tal como estaba en ese momento. |
data.adjustment_note |
WebhookAdjustmentNoteResource | |
data.sale |
SaleResource |
sale.batch.completed
Todas las ventas de un lote enviado por la API llegaron a su resultado.
| Campo | Tipo | Descripción |
|---|---|---|
id |
string (uuid) | Identificador del evento, igual en todos los destinos y reintentos. |
type |
string | Tipo del evento, igual a la cabecera Tezora-Event. |
created_at |
string (date-time) | Momento del hecho, con el desfase de El Salvador. |
data |
object | Objeto del evento, tal como estaba en ese momento. |
data.batch |
SaleBatchResource |
sale.batch.settled
Ninguna venta a la que apunta un lote terminado, también las ya facturadas, sigue pendiente ni en contingencia. Se envía una sola vez, después de Lote de ventas terminado y con los conteos finales; no espera a las rechazadas ni a las fallidas.
| Campo | Tipo | Descripción |
|---|---|---|
id |
string (uuid) | Identificador del evento, igual en todos los destinos y reintentos. |
type |
string | Tipo del evento, igual a la cabecera Tezora-Event. |
created_at |
string (date-time) | Momento del hecho, con el desfase de El Salvador. |
data |
object | Objeto del evento, tal como estaba en ese momento. |
data.batch |
SaleBatchResource |