Webhooks

Cómo recibe su sistema los eventos que Asixto le entrega: la forma del sobre, la verificación de la firma, la deduplicación y qué pasa cuando su receptor no responde.

Es la primera página de la etapa 2 (README): aquí la dirección se invierte y el que expone un endpoint HTTP es usted. No depende de la etapa 1 y no hace falta tener un servidor MCP para implementarla.

1 · Lo que llega

Un POST con content-type: application/json a la URL que usted registre, con el sobre completo en el cuerpo.

{
  "id": "9f1c3a70-4e0b-4f2a-9d5e-2b8c1a6f0d33",
  "type": "job.succeeded",
  "created": 1787923200,
  "environment": "live",
  "data": {}
}

El sobre no lleva versión de la superficie. Hoy hay una sola y un campo con un único valor posible no le permitiría decidir nada; el día que haya una segunda, la que gobierna el sobre será la del endpoint y se anunciará como cambio de contrato (página 09).

No añada suposiciones sobre campos que no están en esta tabla: lo que no aparece aquí, no forma parte del contrato.

2 · Verificar la firma

DEBE verificar toda entrega antes de procesarla. Su endpoint está expuesto a internet y el sobre dispara trabajo en su sistema: sin firma, cualquiera que conozca la URL puede decirle que un trabajo terminó bien.

Cada entrega lleva una cabecera:

Asixto-Signature: t=1787923200,v1=8f2a…c1

El mensaje que se firma es el instante, un punto y el cuerpo exacto que se transmitió:

{t}.{cuerpo crudo}

Cuatro reglas que deciden si su verificador funciona:

1. Firme sobre el cuerpo crudo, no sobre el JSON re-serializado. Si su framework parsea el cuerpo y usted lo vuelve a serializar para verificar, obtiene otros bytes y ninguna entrega válida le va a coincidir. Es el error número uno. En Express se resuelve con express.raw({ type: 'application/json' }) en esa ruta; en FastAPI, con await request.body().
2. Use el texto de t tal como llega, sin convertirlo a número y volver a formatearlo. El mensaje se compone con esa cadena.
3. Compare en tiempo constante (hmac.compare_digest, crypto.timingSafeEqual). Con ==, el tiempo de respuesta revela cuántos caracteres del hexadecimal acertó quien lo intente, y eso convierte falsificar la firma en una búsqueda byte a byte.
4. Recorra todas las firmas v1= y acepte si coincide cualquiera. Comparar solo con la primera funciona hoy y le rompe el día que rote el secreto (sección 3).

La cabecera viaja una sola vez con varias firmas dentro, nunca repetida. Si su pila le entrega una lista de valores para Asixto-Signature, rechace la entrega en vez de unirlos: una cabecera repetida no es nuestra.

Python

import hashlib
import hmac
import time

TOLERANCIA_S = 300


def verificar(cabecera: str | None, cuerpo: bytes, secretos: list[str]) -> bool:
    """`cuerpo` es el cuerpo CRUDO. `secretos` son los que su receptor conoce (uno, o dos al rotar)."""
    if not cabecera:
        return False

    instante: str | None = None
    firmas: list[str] = []
    for parte in cabecera.split(","):
        clave, _, valor = parte.strip().partition("=")
        if clave == "t":
            instante = valor
        elif clave == "v1":
            firmas.append(valor)

    if instante is None or not instante.isdigit() or not firmas:
        return False

    # Ventana SIMÉTRICA: un instante en el futuro también se rechaza.
    if abs(int(time.time()) - int(instante)) > TOLERANCIA_S:
        return False

    mensaje = instante.encode() + b"." + cuerpo
    for secreto in secretos:
        esperada = hmac.new(secreto.encode(), mensaje, hashlib.sha256).hexdigest()
        if any(hmac.compare_digest(firma, esperada) for firma in firmas):
            return True
    return False

TypeScript

import { createHmac, timingSafeEqual } from 'node:crypto';

const TOLERANCIA_S = 300;

const igualSegura = (a: string, b: string): boolean => {
  const x = Buffer.from(a, 'utf8');
  const y = Buffer.from(b, 'utf8');
  // La longitud se compara antes: `timingSafeEqual` exige buffers del mismo tamaño.
  return x.length === y.length && timingSafeEqual(x, y);
};

export const verificar = (cabecera: string | undefined, cuerpo: string, secretos: string[]): boolean => {
  if (!cabecera) return false;

  let instante: string | null = null;
  const firmas: string[] = [];

  for (const parte of cabecera.split(',')) {
    const corte = parte.indexOf('=');
    if (corte <= 0) continue;
    const clave = parte.slice(0, corte).trim();
    const valor = parte.slice(corte + 1).trim();
    if (clave === 't') instante = valor;
    if (clave === 'v1' && valor) firmas.push(valor);
  }

  if (instante === null || !/^[1-9][0-9]*$/.test(instante) || firmas.length === 0) return false;

  const ahora = Math.floor(Date.now() / 1000);
  if (Math.abs(ahora - Number(instante)) > TOLERANCIA_S) return false;

  return secretos.some((secreto) => {
    const esperada = createHmac('sha256', secreto).update(`${instante}.${cuerpo}`, 'utf8').digest('hex');
    return firmas.some((firma) => igualSegura(firma, esperada));
  });
};

Qué devolver

3 · La ventana anti-replay: 300 s, y es simétrica

La ventana la aplica usted, no nosotros. Lo único que hace Asixto es firmar un instante; quien rechaza una entrega capturada y reenviada mañana es su receptor, comparando ese instante con su reloj. Por eso la cifra es parte del contrato público y no una preferencia:

Son los mismos 300 s que trae por omisión el SDK de Stripe, así que si su equipo ya verifica webhooks de Stripe no tiene dos ventanas que razonar.

Lo que sí es distinto: la nuestra es simétrica. La comprobación habitual (ahora - t > tolerancia) deja pasar cualquier instante en el futuro, sin límite. Los relojes derivan en las dos direcciones y en su entorno no hay NTP garantizado, así que una ventana de un solo lado no acota nada por arriba. Compare el valor absoluto, como en los ejemplos de la sección 2.

Si falta: una entrega capturada —en un log, en un proxy, en una traza— se puede reenviar semanas después con su firma intacta, y su sistema la aceptará como nueva.

Rotación del secreto: varias firmas en la misma cabecera

El secreto de firma se rota sin ventana de caída, y eso tiene una consecuencia directa en su código: durante la rotación la cabecera lleva una firma v1= por cada secreto activo, y basta que coincida una.

Hay sitio para dos secretos activos por endpoint, que es lo que hace posible el orden desplegar-luego-revocar. Un receptor que compare solo con la primera firma queda fuera del contrato y pierde entregas justo en el paso 2, que es cuando menos lo espera.

El secreto se reconoce por su prefijo whsec_, para que quien lo vea en un .env o en un log sepa qué es y un escáner de secretos reconozca el patrón. Trátelo como credencial, no como configuración.

4 · Deduplicación: id, durante 7 días

El mismo evento puede llegarle más de una vez. Es la consecuencia inevitable del acuse: si su 2xx se pierde en la red, para nosotros ese intento falló y se reintenta.

Es la misma cifra que ya se le exige en la garantía 1 para la idempotencia de las herramientas, y a propósito: la deduplicación es simétrica —usted descarta por id, nosotros no reemitimos— y dos ventanas distintas dejarían un tramo en el que uno de los dos deja de cumplir sin que el otro lo sepa.

Si falta: un trabajo se procesa dos veces en su sistema porque un acuse se perdió en la red. No es un caso raro ni hipotético: es el comportamiento normal de cualquier cola de entregas.

Orden

No programe contra el orden de llegada. Un reintento puede llegar después de un evento posterior, y eso no es un fallo. Use created y el estado de su propio sistema para decidir.

Lo que sí se sostiene: a un mismo receptor no se le envían dos entregas a la vez de la misma conversación. Entre conversaciones distintas van en paralelo.

5 · Catálogo de eventos

Se suscribe por evento al registrar el endpoint. El catálogo es cerrado: un nombre que no esté en esta tabla se rechaza al dar de alta y al reconfigurar, no al entregar. Si necesita un evento que no está, escálelo (página 10) en vez de inventar el nombre.

Dos precisiones que evitan un diagnóstico equivocado:

• job.expired no es job.failed. El trabajo no falló: terminó sin completarse, y su reacción es distinta (volver a pedirlo, no diagnosticar un error).
• Los dos umbrales de saldo caen en el mismo evento. El porcentaje es un dato de data, no un tipo de evento: con un evento por umbral, cambiar un umbral sería un cambio incompatible del contrato. Y el saldo es el de su empresa, el mismo que consume el resto de la plataforma: un aviso puede nacer de consumo que no entró por la API del Gateway.

La forma de data, evento por evento

data es lo único del sobre que cambia con el type. Aquí está campo por campo, así que puede tipar su receptor y probarlo hoy, sin esperar a recibir una entrega.

Tres reglas que valen para todo el catálogo:

• Los nombres van en snake_case, igual que el resto de la superficie.
• Un campo sin valor viaja en null, no se omite. La única excepción son los tres eventos de saldo, y está dicha en su tabla.
• data no lleva identificadores internos nuestros, y la lista de cada evento es cerrada: un campo que no esté en estas tablas no forma parte del contrato.
• La única clave que trae contenido SUYO es metadata, y solo en los eventos de trabajo: es lo que mandó en la petición (página 15), devuelto tal cual.

job.succeeded y job.failed

Los dos comparten forma. Lo que los distingue es el valor de status, no la lista de campos: el cierre publica el estado guardado del trabajo.

job.expired

La misma forma menos result: un trabajo que venció no produjo ninguno, y una clave en null le invitaría a buscar algo que no existe.

Si su metadata no cupiera, la entrega sale sin él y con metadata_omitted: true en data. Ocurre solo si el resultado del trabajo ya llena por sí solo los 256 KB del cuerpo, porque su metadata está acotado en 4 KB en la puerta. Lo que se cae es el dato de conciliación, nunca el aviso del cierre: perder el aviso de un trabajo ya cobrado sería peor, y usted siempre puede releer el resultado con GET /v1/jobs/{job_id}.

credits.threshold_reached, credits.exhausted, credits.spending_cap_reached

Los tres llevan solo cifras, y son el único caso del catálogo en el que una clave puede faltar: viaja la que el aviso traía medida. No llega en null; si no está, no se midió.

No lleva qué umbral se cruzó, y es deliberado: el dato es usage_percent, así que mover un umbral no rompe su código. Tampoco lleva ningún identificador de su balance, que es nuestro.

certification.finished

Llega al endpoint de test: la batería nunca toca su producción.

webhook_endpoint.disabled

tool.disabled

Llega al endpoint de live: la vigilancia mide las llamadas reales.

conversation.handoff_requested

Es la vía fina: la misma señal viaja dentro del result de job.succeeded, así que si ya lee ese resultado no necesita suscribirse a este evento para enterarse.

6 · Reproducción manual

Una entrega ya terminada se puede volver a enviar desde la aplicación de Asixto. Es para el caso real de toda integración: su receptor respondió 2xx y su código la procesó mal, o usted arregló el bug seis horas después de que se agotaran los reintentos. La alternativa —repetir la operación— se cobra otra vez; reproducir no.

Lo que llega es una entrega nueva:

Deduplique por id; correlacione por replay_of. Esa separación es todo el mecanismo: si la reproducción repitiera el id original, un receptor bien implementado la descartaría por duplicado —que es exactamente lo que le pedimos en la sección 4— y el botón no serviría de nada.

No parsee el id para extraer el original: use replay_of, que es el campo que existe para eso.

Reproducir no vuelve a ejecutar la operación y no toca su facturación: reenvía el cuerpo guardado, tal cual. Y no altera el historial de la entrega original, que se conserva con sus intentos y su último error.

7 · Acuse y reintentos

El único acuse es un 2xx. Respóndalo en cuanto tenga la entrega a salvo —en su propia cola, en su base— y procese después. Su tiempo de proceso no debería depender de nada que pueda tardar.

La escalera es de siete intentos repartidos en unas diez horas:

Los retardos son aproximados a propósito: cada uno se sortea entre la mitad y el total del valor nominal. Sin ese sorteo, una caída nuestra sincronizaría a todos los receptores y volverían todos en el mismo segundo contra sistemas que acaban de levantarse.

Agotada la escalera, la entrega queda agotada: no se vuelve a intentar por sí sola, y a partir de ahí el único camino es la reproducción manual (sección 6). Una entrega agotada cuenta para la desactivación de la sección 8.

El cuerpo de una entrega no pasa de 256 KB. No es un límite contra el que deba dimensionar: es un techo para que un aviso no se convierta en una transferencia.

8 · Desactivación por fallos sostenidos

Un endpoint que deja de recibir de verdad se desactiva, y hacen falta las dos cosas a la vez:

La conjunción es la decisión, no un detalle. Solo con la racha, un endpoint muy usado se apagaría por encajar una ráfaga de minutos durante un despliegue suyo. Solo con la antigüedad, se apagaría un endpoint que nadie usa: un tenant que no cerró ningún trabajo en un día no tiene éxito reciente porque no le mandamos nada, no porque esté roto.

Cuando ocurre, sus otros endpoints activos reciben webhook_endpoint.disabled. Es la razón práctica para registrar más de uno: un endpoint aparte —el de su equipo de guardia— es lo único que puede enterarse de que el principal dejó de recibir.

9 · El endpoint

El secreto de firma se muestra una sola vez, al dar de alta el endpoint y al rotar. Si lo pierde, el camino es rotar: se emite otro sin dejar de firmar con el anterior (sección 3).

Lista de comprobación de su receptor