AzterDocs

Plataforma

Webhooks y eventos

Los hechos de tu operación en Azter —cotizaciones, pagos confirmados, documentos, conversaciones— se entregan a tus sistemas por HTTP con firma HMAC verificable y reintentos automáticos.

Estos son los eventos que el sistema emite hoy:

deal.createdSe crea una cotización u orden en el workspace.
deal.quotedLa cotización pasa a estado quoted (link de pago generado).
deal.paidEl pago fue confirmado (verificación server-side contra el gateway).
deal.invoicedSe emitió el documento tributario asociado.
conversation.createdSe abre una conversación nueva en cualquier canal.
conversation.handoffEl agente deriva el caso a una persona.
message.receivedLlega un mensaje de un cliente por un canal conectado.

Eventos canónicos en camino

El registro canónico de eventos (nombres del tipo commerce.order.created) se está unificando con el Capability Core; este catálogo crecerá con él.

Crear una suscripción

Los endpoints se configuran hoy desde la consola en Configuración → Webhooks: defines la URL de tu sistema, eliges los eventos y recibes el secreto de firma del endpoint. El alta por API llegará junto al REST.

Estructura de la entrega

POST a tu endpoint
1{
2  "id": "evt_••••",
3  "event_type": "deal.paid",
4  "workspace_id": "ws_••••",
5  "created_at": "2026-08-19T22:04:19Z",
6  "data": {
7    "deal_id": "••••-••••",
8    "state": "paid"
9  }
10}

Verificar la firma

Cada entrega incluye la cabecera x-azter-signature con timestamp y HMAC SHA-256 del cuerpo crudo, en el formato t={timestamp},v1={firma}. Verifica siempre antes de procesar.

verify.ts
1import { createHmac, timingSafeEqual } from "node:crypto";
2
3export function verify(rawBody: string, header: string, secret: string) {
4  const [tPart, sPart] = header.split(",");
5  const timestamp = tPart.replace("t=", "");
6  const signature = sPart.replace("v1=", "");
7  const expected = createHmac("sha256", secret)
8    .update(`${timestamp}.${rawBody}`)
9    .digest("hex");
10  const a = Buffer.from(signature);
11  const b = Buffer.from(expected);
12  return a.length === b.length && timingSafeEqual(a, b);
13}

Entrega y reintentos

  • Entrega al menos una vez: usa el id del evento para deduplicar en tu lado.
  • Reintentos automáticos con backoff en 1 min, 5 min, 30 min, 2 h y 6 h, hasta 5 intentos.
  • El despachador corre aproximadamente cada 30 segundos.
  • Orden no garantizado entre tipos distintos; usa created_at para reconstruir la secuencia.

Responde rápido

Devuelve 2xx prontamente y procesa de forma asíncrona. Una respuesta lenta o errónea activa el reintento.
AnteriorAgentesSiguiente Protocolos