Webhooks

Configurar un endpoint

Catálogo de eventos

El payload

{
  "id": "8f3b2c1a-...",              // id único de esta entrega (= header webhook-id)
  "type": "payment.credited",
  "event_at": "2026-07-22T14:47:38.609Z",  // momento del evento: poco después de credited_at (igual a él en un aviso recuperado)
  "data": {
    "payment": {
      "uuid": "f893...",            // id estable del pago (úsalo para correlacionar)
      "folio": "PAY-00000002",
      "status": "credited",         // credited | failed | pending
      "amount_cents": 15000,        // dinero SIEMPRE en centavos + currency
      "credited_amount_cents": 15000,
      "currency": "MXN",
      "provider": "manual",         // manual | stripe | mercadopago | paypal
      "method": null,               // informativo (card | spei | paypal | ...); nunca "manual"
      "bank": null,                 // banco (SPEI-push); null en manual y tarjeta
      "bank_account": "BANORTE0876", // solo manual: la cuenta a la que entró el dinero
      "bank_datetime": "2026-07-22T14:47:00Z", // solo manual, opcional
      "files": [                    // comprobantes (solo manual); [] si no hay
        { "uuid": "92c9...", "name": "comprobante.pdf", "mime_type": "application/pdf" }
      ],
      "transaction_id": null,       // online: id del proveedor; manual: id de banca capturado al acreditar (null si no se capturó)
      "receipt_url": null,          // null en manual; página del recibo en online acreditado
      "fail_reason": null,          // solo con valor en payment.failed: el motivo EN TEXTO LIBRE que escribió tu equipo
      "credited_at": "2026-07-22T14:47:38.204Z",
      "description": "Abono parcial del pedido 4471",  // nota del pago escrita por tu equipo o por tu AI employee; null si no hay
      "custom_fields": {                                // los campos personalizados que definiste; {} si no hay ninguno
        "Tipo de pago": "Abono",
        "Pedido": "4471"
      }
    },
    "conversation_info": {
      "uuid": "c9ba...",            // null si la conversación se borró
      "phone": "529671941293",
      "inbox_status": "pending",
      "is_tester": false,           // false en estos webhooks: no emiten pagos de prueba
      "mailbox": { "name": "Ventas" }
    },
    "contact_info": {
      "first_name": "Maikol",
      "middle_name": null,
      "last_name": null,
      "second_last_name": null,
      "full_name": "Maikol",
      "username": null,             // handle de WhatsApp (sin "@"), si se conoce
      "phone": "529671941293",
      "whatsapp_user_id": "MX.1343..." // identidad de WhatsApp (o el teléfono si aún no hay BSUID)
    }
  }
}

description y custom_fields: el contexto que escribe tu equipo

• description es la nota del pago. La escribe quien lo registra desde el panel, o la redacta tu AI employee si le configuraste una guía para eso. Es prosa libre: null cuando nadie escribió nada.
• custom_fields son los campos personalizados que definiste en tu cuenta —«Tipo de pago», «Pedido», los que necesites— con el valor que se capturó en ese pago. Mientras el campo esté en despliegue por etapas la clave puede no venir; cuando viene es siempre un objeto: {} si no se capturó ninguno.

Si recibes eventos por dos vías, deduplica por payment.uuid

Lo que responde tu endpoint puede continuar la conversación

• El cuerpo de tu respuesta se le muestra a un modelo. Contesta solo con lo que te parezca bien que el cliente llegue a saber: ni credenciales, ni datos de otro cliente, ni volcados internos. Si es largo, se recorta. Antes de mostrárselo tapamos los valores de los campos con nombre de credencial (token, password, api_key…), los números de 18 dígitos —aunque vengan partidos por espacios o guiones— y la parte /pay/… de los enlaces, así que si tu respuesta trae una CLABE o un enlace con /pay/…, el AI no podrá pasárselos al cliente. Ese filtro es una red y no una garantía: no reconoce todos los nombres de campo ni los enlaces de otras pasarelas, así que no mandes credenciales ni datos bancarios confiando en él.
• Solo se lee si respondes 2xx y con cuerpo, y ni así es seguro. Un error o una respuesta vacía no continúan nada, y ese despacho no se repite si respondes 4xx o 5xx. Solo se repite una vez si no respondes en 30 segundos o falla la conexión, así que puede llegarte dos veces y sin clave de idempotencia: este despacho no lleva webhook-id ni firma, así que la deduplicación corre por tu cuenta. Los reintentos, el timeout y el webhook-id de Entrega y reintentos son solo de los webhooks de eventos de pago. Sí se continúa aunque en ese momento la conversación la atienda una persona o esté pendiente. No hay un plazo garantizado entre tu respuesta y el mensaje al cliente.
• La cadena tiene un tope, y depende de dónde salió el despacho. Si la continuación vuelve a despachar a tu URL, esa respuesta también puede continuar la conversación, hasta el tope:
  • Hasta dos continuaciones cuando el despacho sale de lo que abre el turno: el empleado JSON que corre por sí mismo —el asignado, o uno lanzado directamente desde el panel, una campaña o esta API—, una acción send_json suelta en un grupo de acciones, o el action set del empleado que responde un mensaje del cliente, un mensaje programado o el botón «Ejecutar» sobre el asignado (con un send_json suyo o un empleado JSON que ese set lanza).
  • Una sola cuando despacha el action set de un empleado que otro lanzó: otro action set, esta API (run_ai, ai_assistance, assign_ai_employee con run: true o Smart Actions), una campaña, o «Ejecutar» sobre un empleado que no es el asignado. También se queda en una el empleado JSON que ese set lance.
  El tope es por cadena, no por conversación: cada mensaje del cliente la vuelve a empezar.
• Una campaña te despacha una vez por destinatario. Si el equipo del negocio pone un send_json o un empleado JSON en una campaña, te llega una petición por destinatario, y con el procesamiento configurado cada respuesta puede continuar su conversación. Un send_json que va antes de la primera acción de AI de la campaña sale al ritmo del envío. Si va después, sale desde una cola que acota cuántos arrancan a la vez por negocio, pero no cuántos siguen corriendo: uno que tarda puede liberar su lugar antes de terminar. No hay un ritmo garantizado. Dimensiona tu endpoint por el tamaño de la audiencia, no por el de una conversación.
• No aplica a los despachos que llevan el campo del pago, aunque no traiga ningún pago (un arreglo vacío, o un objeto con data vacío). Ahí la respuesta no se lee, por diseño: un endpoint que hace eco del request devolvería datos bancarios, y el corte no distingue un campo sin pagos de uno con pagos.

fail_reason: texto libre escrito por una persona

Headers de cada entrega

Verificar la firma

import { Webhook } from "standardwebhooks";

// whsec_… guardado en una variable de entorno
const wh = new Webhook(process.env.WEBHOOK_SECRET);

// rawBody = el cuerpo crudo del request (string), NO el objeto ya parseado
const payload = wh.verify(rawBody, {
  "webhook-id": req.headers["webhook-id"],
  "webhook-timestamp": req.headers["webhook-timestamp"],
  "webhook-signature": req.headers["webhook-signature"],
});
// Si la firma no valida, verify() lanza — responde 400 y no proceses.

import os
from standardwebhooks import Webhook

wh = Webhook(os.environ["WEBHOOK_SECRET"])

# raw_body = el cuerpo crudo del request (bytes/str), NO el dict ya parseado
payload = wh.verify(raw_body, {
    "webhook-id": headers["webhook-id"],
    "webhook-timestamp": headers["webhook-timestamp"],
    "webhook-signature": headers["webhook-signature"],
})
# Si la firma no valida, verify() lanza — responde 400 y no proceses.

import crypto from "crypto";

function verifyWebhook(rawBody, headers, secret) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];

  // Rechaza replays fuera de ±5 min (el webhook-timestamp entra en la firma).
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(ts)) > 300) return false;

  const signedContent = `${id}.${ts}.${rawBody}`;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto.createHmac("sha256", key).update(signedContent).digest("base64");

  // El header puede traer varias firmas (rotación), separadas por espacio.
  const received = headers["webhook-signature"]
    .split(" ")
    .map((s) => s.replace(/^v1,/, ""));

  return received.some((sig) => {
    const a = Buffer.from(sig);
    const b = Buffer.from(expected);
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

import base64, hashlib, hmac, time

def verify_webhook(raw_body: str, headers: dict, secret: str) -> bool:
    # Rechaza replays fuera de ±5 min (el webhook-timestamp entra en la firma).
    if abs(int(time.time()) - int(headers["webhook-timestamp"])) > 300:
        return False

    signed_content = f'{headers["webhook-id"]}.{headers["webhook-timestamp"]}.{raw_body}'

    key = base64.b64decode(secret.removeprefix("whsec_"))
    expected = base64.b64encode(
        hmac.new(key, signed_content.encode(), hashlib.sha256).digest()
    ).decode()

    # El header puede traer varias firmas (rotación), separadas por espacio.
    received = [s.removeprefix("v1,") for s in headers["webhook-signature"].split(" ")]
    return any(hmac.compare_digest(sig, expected) for sig in received)

Entrega y reintentos

Rotar el secret

Comprobantes

curl "https://app.1to1ai.com/api/v1/public/{slug}/payments/{paymentUuid}/files/{fileUuid}" \
  -H "Authorization: Bearer sk_1to1_tu_api_key"

{
  "download_url": "https://...",
  "expires_at": "2026-07-22T15:17:38.609Z"
}

Próximos pasos