Notificaciones por API: leads y alertas del bot en tu servidor

Qué notificaciones llegan

Los eventos de tokens se refieren al saldo de toda la cuenta, no a un bot, por eso llegan a las URL de todos los bots con API activada. Varios bots con la misma URL reciben una sola solicitud.

Cómo conectarlo

1. 1

   Abre las notificaciones del bot

   Ve a Recepción → Bots, elige el bot y abre la pestaña Notificaciones. En la fila API pulsa Configurar notificaciones.

2. 2

   Pega la URL del receptor

   En URL del receptor escribe la dirección que acepta solicitudes POST: el endpoint de tu CRM, un disparador webhook de Make o n8n, o un Catch Hook de Zapier. La URL debe empezar por https://.

3. 3

   Pulsa Probar

   Se envía a la URL un lead de ejemplo con el evento test. Debajo del botón verás el código de respuesta, el tiempo y el inicio de la respuesta de tu servidor. Un código 2xx significa que funciona. No hace falta guardar la URL antes de probar.

   La prueba se puede lanzar hasta 5 veces por minuto por bot, para que la configuración nunca se convierta en una avalancha de solicitudes a un servidor ajeno.

4. 4

   Guarda

   Pulsa Guardar: la fila API de la lista de notificaciones pasa a Notificaciones configuradas. Para dejar de enviar, pulsa Desactivar en la misma ventana.

Solo se aceptan URL HTTPS. Las direcciones internas y locales (localhost, 10.x, 192.168.x, etc.) se rechazan: el receptor debe ser accesible desde internet.

Formato de la solicitud

Método POST, cuerpo JSON en UTF-8. El tipo de notificación está en el campo event y en el encabezado X-Webhook-Event. El campo type se mantiene por compatibilidad con integraciones antiguas (lead_new, lead_update, bot_chat_have_mistake, tokens_threshold, tokens_depleted, bot_reply_no_balance, lead_test).

Lead: lead.created y lead.updated

{
  "event": "lead.created",
  "type": "lead_new",
  "bot_id": "c8df2a84-9b17-4bf9-9248-9cee74eaeee6",
  "data": {
    "lead": {
      "id": "9b2f6c1e-…",
      "name": "Anna",
      "phone": "+15551234567",
      "email": "[email protected]",
      "telegram_username": null,
      "city": "Austin",
      "address": null,
      "scheduled_call": null,
      "type_payment": null,
      "need_delivery": null,
      "delivery_time": null,
      "meeting_date_time_office": null,
      "meeting_date_time_client": null,
      "extended_info": null,
      "status": "NEW",
      "comment": "Wants a quote for 3 rooms"
    },
    "botChatId": 12345,
    "shortInfo": "Wants a renovation quote for three rooms, asks for a call in the evening",
    "messages": "Client: …\nBot: …",
    "linkToChat": "https://…",
    "channelUrl": "https://…"
  },
  "timestamp": "2026-09-21T12:00:00.000Z",
  "delivery_id": "3f1c2a4e-…"
}

• data.lead.id es el mismo en lead.created y en cada lead.updated de un lead: úsalo para actualizar el registro en tu sistema.
• Los campos que el bot no recogió llegan como null.
• shortInfo es el resumen de la conversación y messages la transcripción: breve o completa según el ajuste del bot ¿Cómo dar formato a la notificación en Telegram?.
• linkToChat enlaza a la conversación en el canal de origen cuando la plataforma lo ofrece.

Se necesita ayuda: chat.help_needed

{
  "event": "chat.help_needed",
  "type": "bot_chat_have_mistake",
  "bot_id": "c8df2a84-9b17-4bf9-9248-9cee74eaeee6",
  "data": {
    "reason": "bot_asked",
    "botId": "c8df2a84-9b17-4bf9-9248-9cee74eaeee6",
    "botChatId": 12345,
    "shortInfo": "The client asks about a custom order",
    "messages": "Client: …\nBot: …",
    "linkToChat": "https://…"
  },
  "timestamp": "2026-09-21T12:05:00.000Z",
  "delivery_id": "…"
}

El bot en este chat ya se pausó y espera a una persona: abre la conversación con linkToChat o en Chats y responde tú al cliente.

Saldo de tokens: tokens.*

{
  "event": "tokens.low",
  "type": "tokens_threshold",
  "bot_id": "c8df2a84-9b17-4bf9-9248-9cee74eaeee6",
  "bot_ids": [
    "c8df2a84-9b17-4bf9-9248-9cee74eaeee6",
    "5e0a7d31-…"
  ],
  "data": {
    "tokensRemaining": 50000
  },
  "timestamp": "2026-09-21T13:00:00.000Z",
  "delivery_id": "…"
}

Los eventos de tokens llegan una vez por URL: bot_ids enumera todos los bots con esta URL y bot_id es el bot cuyo secreto firmó la solicitud. Usa tokens.low para recargar a tiempo y trata tokens.depleted y tokens.bot_silent como alarmas: los clientes se quedan sin respuesta.

Verificación de la firma

El secreto de firma está en la misma ventana, en el bloque Secreto de firma (botones Mostrar y Copiar). Cada bot tiene su propio secreto. La firma es el HMAC-SHA256 de la cadena X-Webhook-Timestamp + . + el cuerpo sin procesar, con el secreto como clave, en hex y con el prefijo sha256=. Calcúlala sobre el cuerpo antes de parsear el JSON: un JSON re-serializado puede no coincidir byte a byte.

import crypto from "node:crypto";

// rawBody: the request body as a string, BEFORE JSON.parse
function isValid(rawBody, headers, secret) {
  const expected =
    "sha256=" +
    crypto
      .createHmac("sha256", secret)
      .update(headers["x-webhook-timestamp"] + "." + rawBody)
      .digest("hex");
  const got = headers["x-webhook-signature"] || "";
  return (
    got.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))
  );
}

import hashlib, hmac

def is_valid(raw_body: bytes, headers, secret: str) -> bool:
    message = headers["X-Webhook-Timestamp"].encode() + b"." + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, headers.get("X-Webhook-Signature", ""))

Para rechazar repeticiones, compara X-Webhook-Timestamp con la hora actual (por ejemplo, no más de 5 minutos) y guarda los delivery_id ya procesados.

Si el secreto se filtra, pulsa Generar nuevo: el anterior deja de funcionar al instante, así que actualízalo en tu servidor.

Entrega y respuesta de tu servidor

• Responde con un código 2xx en 10 segundos. Haz el procesamiento pesado después de responder, en segundo plano.
• No se siguen redirecciones: indica la URL final.
• Los envíos fallidos no se reintentan. La notificación por API se pierde, pero los demás canales (Telegram, correo, CRM) siguen funcionando y el lead queda en Leads.
• La API funciona junto con los demás canales, no en su lugar: puedes recibir leads en Telegram y en tu sistema a la vez.