Webhooks — referencia para integradores

Ajustes → Integraciones y automatización (/settings/integrations). Das de alta una URL, eliges eventos y recibes un POST JSON firmado cada vez que ocurre algo. Pensado para n8n, Make, Zapier o tu propio endpoint.

Fuente de verdad: crates/vs-core/src/webhooks.rs. Si algo de aquí no cuadra con el código, manda el código.

1. Envelope

Todos los eventos llegan con la misma envoltura:

{
  "id": "evt_01J8Z9K2QX7M3B4N5P6R7S8T9V",
  "type": "call.ended",
  "created_at": "2026-07-19T04:12:33.481+00:00",
  "org_id": "01J8...",
  "data": { }
}

Los campos son estables; pueden aparecer campos nuevos dentro de data. Ignora los que no conozcas en vez de fallar.

2. Eventos

Existe además ping, que solo se emite con el botón Probar del panel. No se puede suscribir y no aparece en el catálogo.

Aviso de PII: transcript.ready incluye text, turns y qa — es decir, el contenido literal de la conversación. Lo mismo chat.message.created (el texto de cada mensaje), chat.closed (el resumen), chat.rated (el comentario del visitante) y chat.qa_scored (resumen e incidencias de la atención). chat.started, chat.closed y chat.handed_off llevan además visitor.email y visitor.name tal como los dio el visitante. Trata ese endpoint con el mismo cuidado que la grabación: TLS, control de acceso y una retención que puedas justificar.

2.bis Campos de data, evento por evento

Todo lo de aquí sale de crates/vs-core/src/webhooks.rs y de los puntos de emisión. Un campo puede llegar null si el dato no existe para esa llamada (una saliente no tiene queue_id, una que nadie contestó no tiene answered_at). Trata la ausencia y el null igual.

call.started

call.ended

Todos los de call.started (con answered_at ya nullable) más:

call.transferred

transcript.ready

⚠️ Los cuatro últimos campos son datos personales. Es el único evento que transporta el contenido de la conversación. Ver el aviso de PII de la sección 2.

Los estados de transcription_status son pending · processing · success · failed · skipped (y NULL si la organización no transcribe). No hay done: esta tabla lo dijo durante meses y el filtro del barrido se escribió contra ese valor, así que el evento no se emitió nunca. [audit transcript-ready-done]

appointment.booked

El mismo type sale de tres sitios: la reserva del agente por voz, el alta del panel de Agenda y POST /v1/appointments. Significan lo mismo —una cita nueva—, pero el data no trae los mismos campos, así que la tabla dice cuál llega en cada caso.

Los tres últimos llegan null por voz cuando no hay dato, y como cadena vacía desde el panel y la API. Un if (data.email) cubre los dos; un === null, no.

appointment.cancelled

Solo agenda nativa, y sale de los tres sitios donde se puede anular: el agente por voz, el panel de Agenda y POST /v1/appointments/{id}/cancel. Con Cal.com o Google la baja la da su sistema, no el nuestro.

No lleva end, ni source, ni party_size, ni email, ni note: lo que no venga aquí, sácalo del booked que ya recibiste con ese event_id.

callback.created

campaign.finished

campaign.contact_completed

Sale cuando termina el flujo de una llamada de campaña con agente IA que se contestó. Si no contestan, no sale (eso lo cuentan los reintentos de la campaña y call.ended). En campañas con agentes humanos no sale: allí el flujo solo precede a la persona.

qa.scored

chat.started

chat.message.created

Los rastros de la llamada web (role: "event", kind webcall_started / webcall_ended) no se emiten por este evento: se leen por GET /v1/chats/{chat_id} (ver docs/API.md, chatbots).

Todos los chat.* se emiten solo si algún endpoint de la organización está suscrito: el emisor lo comprueba antes con una caché de un minuto por org y evento, así que un endpoint nuevo tarda hasta 60 s en empezar a recibir cualquiera de ellos (no solo chat.message.created).

chat.closed

Se emite una sola vez por cierre aunque dos caminos cierren a la vez: el cierre es condicional en BD y solo el que lo consigue avisa. La clave de idempotencia es el chat más el instante del cierre, así que una conversación que se reabre y se vuelve a cerrar emite otra vez (con el resumen final). Llega unos segundos DESPUÉS del cierre, porque espera al resumen.

chat.handed_off

Solo sale cuando la conversación entra de verdad en la cola (hay alguien asignado y conectado, y está dentro del horario). Si no hay nadie, la conversación pasa a «deja tu mensaje» y no se emite. La clave de idempotencia es el chat más el instante del paso: una conversación que se reabre y vuelve a pedir persona emite otra vez.

chat.rated

Una conversación se valora una vez: la segunda valoración se rechaza y no emite nada.

chat.qa_scored

Estos campos son fijos: los produce siempre el evaluador de conversaciones de chatbot (en qa.scored de llamadas, en cambio, la forma depende de la plantilla de la org). Solo sale para chatbots con la evaluación activada, en planes con pasar a persona y evaluación de calidad, y para conversaciones con al menos un mensaje de una persona del equipo. Llega unos segundos después de chat.closed; si la evaluación falla se reintenta (hasta tres intentos en total, contando el primero) y no se emite nada mientras tanto. Sin saldo o con el tope diario del chatbot alcanzado se aplaza, y a los 7 días del cierre se abandona.

3. Cabeceras

No enviamos cabecera con el número de reintento. Para saber si es un reintento, mira si ya procesaste ese X-Alpire-Delivery.

4. Verificar la firma

Estilo Stripe: se firma "<timestamp>.<body-crudo>" con HMAC-SHA256 y el secreto del endpoint, en hexadecimal.

firma = hex( HMAC_SHA256( secreto, timestamp + "." + body ) )

El secreto se muestra una sola vez al crear el webhook. Si lo pierdes, rótalo desde el panel (botón «Rotar secreto» al editar el webhook): no hace falta borrarlo y recrearlo.

Cuatro reglas que no puedes saltarte:

1. Firma sobre el body crudo, antes de parsear el JSON. Si serializas de nuevo, cambian espacios y orden y la firma no cuadra.
2. Compara en tiempo constante (timingSafeEqual / hmac.compare_digest), no con ==.
3. Rechaza la entrega si falta X-Alpire-Timestamp o X-Alpire-Signature, y después rechaza timestamps viejos (5 minutos es razonable) o aceptas replays. El orden importa: en JavaScript Number(undefined) es NaN y Math.abs(NaN) > 300 es false, así que un control de antigüedad sin comprobar antes la cabecera deja pasar una petición sin ella; en Python int("") lanza y tu servidor contesta 500.
4. La cabecera puede traer varias firmas separadas por coma, y la entrega es buena si cualquiera cuadra con tu secreto.

Rotar el secreto sin cortes

Al rotar el secreto en el panel, durante 24 horas cada entrega lleva dos firmas: primero la del secreto nuevo y después la del anterior (sha256=<nueva>,sha256=<anterior>). Así puedes cambiar el secreto en tu automatización cuando te venga bien: mientras tengas el viejo, cuadra la segunda; en cuanto pongas el nuevo, cuadra la primera. Pasadas las 24 horas solo va la del nuevo. El panel enseña hasta cuándo dura la firma doble.

Si rotas porque el secreto se ha filtrado, cambia el tuyo cuanto antes: la firma doble no le da nada a quien tenga el viejo (con él ya podía firmar lo que quisiera), pero tu endpoint lo sigue aceptando hasta que lo cambies.

Node.js / Express

const crypto = require('crypto');

// La entrega es buena si CUALQUIERA de las firmas de la cabecera cuadra con tu secreto.
function firmaValida(secreto, ts, cuerpo, cabecera) {
  const esperada = Buffer.from('sha256=' + crypto
    .createHmac('sha256', secreto)
    .update(ts + '.' + cuerpo)
    .digest('hex'));
  return cabecera.split(',').some((f) => {
    const recibida = Buffer.from(f.trim());
    return recibida.length === esperada.length && crypto.timingSafeEqual(recibida, esperada);
  });
}

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const ts   = req.get('X-Alpire-Timestamp');
  const sig  = req.get('X-Alpire-Signature');
  const body = req.body.toString('utf8');       // cuerpo CRUDO

  // Primero que existan: sin esto, Number(undefined) es NaN y el control de antigüedad
  // de la línea siguiente no rechaza nada.
  if (!ts || !sig || !/^\d+$/.test(ts)) return res.status(400).end();
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.status(400).end();
  if (!firmaValida(process.env.WEBHOOK_SECRET, ts, body, sig)) return res.status(401).end();

  const event = JSON.parse(body);
  // Idempotencia: si ya viste req.get('X-Alpire-Delivery'), responde 200 y no repitas.
  res.status(200).end();                        // responde YA, procesa en background
});

Python / Flask

import hmac, hashlib, time
from flask import request, abort

def firma_valida(secreto: bytes, ts: str, cuerpo: bytes, cabecera: str) -> bool:
    esperada = "sha256=" + hmac.new(secreto, ts.encode() + b"." + cuerpo, hashlib.sha256).hexdigest()
    # La entrega es buena si CUALQUIERA de las firmas cuadra (dos durante una rotación).
    return any(hmac.compare_digest(f.strip(), esperada) for f in cabecera.split(","))

@app.post("/webhook")
def webhook():
    ts   = request.headers.get("X-Alpire-Timestamp", "")
    sig  = request.headers.get("X-Alpire-Signature", "")
    body = request.get_data()                    # bytes crudos

    # Primero que existan y sean lo que dicen: int("") lanza y Flask contesta 500.
    if not ts.isdigit() or not sig:
        abort(400)
    if abs(time.time() - int(ts)) > 300:
        abort(400)
    if not firma_valida(SECRET.encode(), ts, body, sig):
        abort(401)

    return "", 200

5. Códigos de respuesta y reintentos

Lo que miramos es solo el código HTTP. El cuerpo de tu respuesta se ignora.

Tienes 10 segundos para responder. Responde 2xx en cuanto valides la firma y haz el trabajo en segundo plano; si procesas en línea y tardas, te reintentaremos una entrega que en realidad sí procesaste.

Backoff entre intentos (segundos), según intentos ya realizados:

Tras 8 intentos (unos 2,4 días) la entrega pasa a failed (dead-letter): aparece en la lista de Entregas del webhook con su último error, en Ajustes → Depuración como webhook_failed, y avisamos por correo a los administradores de la organización la primera vez que pasa. No volvemos a avisar de ese webhook hasta que entregue bien otra vez: con el endpoint caído fallan todas, y cien correos iguales no ayudan a nadie.

Reenviar. Una entrega failed de los últimos 7 días se puede reenviar desde «Entregas» (con el webhook activo): vuelve a la cola con los 8 intentos desde cero y el mismo X-Alpire-Delivery, que tu endpoint no llegó a procesar.

No hay orden garantizado

Las entregas salen en paralelo —varias a la vez, repartidas entre organizaciones y, con varios nodos, desde más de uno— y un reintento sale detrás de lo que se generó después: un call.started que falla a la primera puede llegarte después de su call.ended. Si tu integración necesita orden:

1. Agrupa por el recurso: call_id, chat_id, el event_id de una cita, callback_id…
2. Ordena por las marcas de tiempo de data (answered_at, ended_at, closed_at, handed_off_at…), no por el orden de llegada. El created_at del envelope sirve de desempate, pero es cuándo se generó el evento: en los tres eventos de barrido (call.*, transcript.ready) es el momento del barrido, no el de la llamada.
3. Al actualizar tu copia, descarta un evento más viejo que el último que ya aplicaste para ese recurso.

⚠️ Un 4xx no detiene los reintentos. Hoy no distinguimos "no puedo procesarlo ahora" de "esto nunca va a funcionar": un 400 o un 410 Gone permanente se reintenta las 8 veces igual, repartidas a lo largo de más de un día. Si tu endpoint desaparece, borra o pausa el webhook en el panel; no basta con devolver un error.

6. Estado en el panel

En la lista de webhooks verás el resultado del último intento:

El botón Entregas enseña las últimas 100 de los últimos 7 días: cuándo, evento, estado, intentos, próximo intento y el último error de cada una, con «Reenviar» en las fallidas.

Pausar un webhook congela sus entregas pendientes (no gastan intentos mientras tanto) y se conservan 7 días: si no lo reactivas antes, se descartan. El panel te dice cuántas quedan al pausar.

Las entregas se guardan 7 días (retención corta a propósito: transcript.ready lleva PII) y luego se purgan.

7. Restricciones de la URL

Solo http:// y https://. Se resuelve el DNS antes de enviar y se rechaza si alguna IP resultante es privada o especial:

La IP resuelta queda fijada para esa petición, así que un DNS rebinding tampoco entra.

Se valida al crear el webhook y en cada entrega. En la práctica: tu endpoint tiene que estar en Internet público. Para desarrollo, usa un túnel (ngrok, Cloudflare Tunnel).

Limitaciones conocidas

• No hay orden garantizado entre entregas, ni siquiera del mismo recurso. Cómo ordenar, en §5.
• Un 4xx no detiene los reintentos (§5): si tu endpoint desaparece, borra o pausa el webhook en el panel.
• El data de appointment.booked no es el mismo según quién reserve: por voz no van end, source ni resource_id; desde el panel y desde la API no va call_id (y su clave se omite, no llega a null). La tabla de la sección 2.bis lo detalla campo a campo.
• Los eventos call.started / call.ended / transcript.ready salen de un barrido cada 15 s, así que tienen esa latencia; los demás se emiten en el momento.