Tezora

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>
  1. Leer el cuerpo crudo, antes de decodificar el JSON.
  2. Separar t y cada valor sha256.
  3. Rechazar si t difiere en más de 5 minutos de la hora actual.
  4. Calcular el HMAC de t + "." + cuerpo y compararlo en tiempo constante con cada sha256. 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