Webhooks

Configurar um endpoint

Catálogo de eventos

O payload

{
  "id": "8f3b2c1a-...",              // id único desta entrega (= header webhook-id)
  "type": "payment.credited",
  "event_at": "2026-07-22T14:47:38.609Z",  // momento do evento: logo após credited_at (igual a ele num aviso recuperado)
  "data": {
    "payment": {
      "uuid": "f893...",            // id estável do pagamento (use para correlacionar)
      "folio": "PAY-00000002",
      "status": "credited",         // credited | failed | pending
      "amount_cents": 15000,        // dinheiro SEMPRE em 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 em manual e cartão
      "bank_account": "BANORTE0876", // só manual: a conta em que o dinheiro entrou
      "bank_datetime": "2026-07-22T14:47:00Z", // só manual, opcional
      "files": [                    // comprovantes (só manual); [] se não houver
        { "uuid": "92c9...", "name": "comprovante.pdf", "mime_type": "application/pdf" }
      ],
      "transaction_id": null,       // online: id do provedor; manual: id de banco capturado ao creditar (null se não foi capturado)
      "receipt_url": null,          // null em manual; página do recibo em online creditado
      "fail_reason": null,          // só com valor em payment.failed: o motivo EM TEXTO LIVRE que sua equipe escreveu
      "credited_at": "2026-07-22T14:47:38.204Z",
      "description": "Pagamento parcial do pedido 4471",  // nota do pagamento escrita pela sua equipe ou pelo seu AI employee; null se não houver
      "custom_fields": {                                  // os campos personalizados que você definiu; {} se não houver nenhum
        "Tipo de pagamento": "Parcela",
        "Pedido": "4471"
      }
    },
    "conversation_info": {
      "uuid": "c9ba...",            // null se a conversa foi excluída
      "phone": "529671941293",
      "inbox_status": "pending",
      "is_tester": false,           // false nestes webhooks: não emitem pagamentos de teste
      "mailbox": { "name": "Vendas" }
    },
    "contact_info": {
      "first_name": "Maikol",
      "middle_name": null,
      "last_name": null,
      "second_last_name": null,
      "full_name": "Maikol",
      "username": null,             // handle do WhatsApp (sem "@"), se conhecido
      "phone": "529671941293",
      "whatsapp_user_id": "MX.1343..." // identidade do WhatsApp (ou o telefone se ainda não houver BSUID)
    }
  }
}

description e custom_fields: o contexto que sua equipe escreve

• description é a nota do pagamento. Quem o registra a escreve no painel, ou seu AI employee a redige se você configurou um guia para isso. É prosa livre: null quando ninguém escreveu nada.
• custom_fields são os campos personalizados que você definiu na sua conta —«Tipo de pagamento», «Pedido», os que precisar— com o valor capturado naquele pagamento. Enquanto o campo estiver em liberação por etapas a chave pode não vir; quando vem é sempre um objeto: {} se nenhum foi capturado.

Se você recebe eventos por duas vias, deduplique por payment.uuid

O que seu endpoint responde pode continuar a conversa

• O corpo da sua resposta é mostrado a um modelo. Responda só com aquilo que você aceita que o cliente venha a saber: nem credenciais, nem dados de outro cliente, nem dumps internos. Se for longo, é truncado. Antes de mostrá-lo ocultamos os valores dos campos com nome de credencial (token, password, api_key…), os números de 18 dígitos —mesmo separados por espaços ou hífens— e a parte /pay/… dos links, então se a sua resposta trouxer uma CLABE ou um link com /pay/…, o AI não vai conseguir repassá-los ao cliente. Esse filtro é uma rede de proteção, não uma garantia: ele não reconhece todos os nomes de campo nem os links de outras gateways, então não envie credenciais nem dados bancários contando com ele.
• Só é lida se você responder 2xx e com corpo, e mesmo assim não é garantido. Um erro ou uma resposta vazia não continuam nada, e esse despacho não é repetido se você responder 4xx ou 5xx. Ele só se repete uma vez se você não responder em 30 segundos ou a conexão falhar, então pode chegar duas vezes e sem chave de idempotência: este despacho não leva webhook-id nem assinatura, então a deduplicação fica por sua conta. Os reenvios, o timeout e o webhook-id de Entrega e reenvios são apenas dos webhooks de eventos de pagamento. Continua, sim, mesmo que naquele momento uma pessoa esteja atendendo a conversa ou ela esteja pendente. Não há um prazo garantido entre a sua resposta e a mensagem ao cliente.
• A cadeia tem um teto, e ele depende de onde saiu o despacho. Se a continuação despachar de novo para a sua URL, essa resposta também pode continuar a conversa, até o teto:
  • Até duas continuações quando o despacho sai do que abre o turno: o funcionário JSON que roda por conta própria —o atribuído, ou um disparado diretamente pelo painel, por uma campanha ou por esta API—, uma ação send_json avulsa em um grupo de ações, ou o action set do funcionário que responde a uma mensagem do cliente, a uma mensagem agendada ou ao botão «Executar» sobre o atribuído (com um send_json dele ou um funcionário JSON que esse set dispara).
  • Uma só quando despacha o action set de um funcionário que outro disparou: outro action set, esta API (run_ai, ai_assistance, assign_ai_employee com run: true ou Smart Actions), uma campanha, ou «Executar» sobre um funcionário que não é o atribuído. Também fica em uma o funcionário JSON que esse set dispara.
  O teto é por cadeia, não por conversa: cada mensagem do cliente a começa de novo.
• Uma campanha despacha para você uma vez por destinatário. Se a equipe do negócio coloca um send_json ou um funcionário JSON em uma campanha, chega a você uma requisição por destinatário, e com o processamento configurado cada resposta pode continuar a sua conversa. Um send_json que vai antes da primeira ação de AI da campanha sai no ritmo do envio. Se vai depois, sai de uma fila que limita quantos começam ao mesmo tempo por negócio, mas não quantos continuam rodando: um que demora pode liberar o seu lugar antes de terminar. Não há um ritmo garantido. Dimensione o seu endpoint pelo tamanho da audiência, não pelo de uma conversa.
• Não se aplica aos despachos que levam o campo do pagamento, mesmo que não traga nenhum pagamento (um array vazio, ou um objeto com data vazio). Ali a resposta não é lida, por design: um endpoint que ecoa a requisição devolveria dados bancários, e o corte não distingue um campo sem pagamentos de um com pagamentos.

fail_reason: texto livre escrito por uma pessoa

Headers de cada entrega

Verificar a assinatura

import { Webhook } from "standardwebhooks";

// whsec_… guardado em uma variável de ambiente
const wh = new Webhook(process.env.WEBHOOK_SECRET);

// rawBody = o corpo cru do request (string), NÃO o objeto já parseado
const payload = wh.verify(rawBody, {
  "webhook-id": req.headers["webhook-id"],
  "webhook-timestamp": req.headers["webhook-timestamp"],
  "webhook-signature": req.headers["webhook-signature"],
});
// Se a assinatura não validar, verify() lança — responda 400 e não processe.

import os
from standardwebhooks import Webhook

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

# raw_body = o corpo cru do request (bytes/str), NÃO o dict já parseado
payload = wh.verify(raw_body, {
    "webhook-id": headers["webhook-id"],
    "webhook-timestamp": headers["webhook-timestamp"],
    "webhook-signature": headers["webhook-signature"],
})
# Se a assinatura não validar, verify() lança — responda 400 e não processe.

import crypto from "crypto";

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

  // Rejeita replays fora de ±5 min (o webhook-timestamp faz parte da assinatura).
  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");

  // O header pode trazer várias assinaturas (rotação), separadas por espaço.
  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:
    # Rejeita replays fora de ±5 min (o webhook-timestamp faz parte da assinatura).
    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()

    # O header pode trazer várias assinaturas (rotação), separadas por espaço.
    received = [s.removeprefix("v1,") for s in headers["webhook-signature"].split(" ")]
    return any(hmac.compare_digest(sig, expected) for sig in received)

Entrega e reenvios

Rotacionar o secret

Comprovantes

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

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

Próximos passos