Visão geral de webhooks

Webhooks permitem que sua plataforma reaja à atividade de pagamento no momento em que ela acontece. À medida que transações, reembolsos, disputas e assinaturas mudam de estado nos seus provedores conectados, a Tokeflow faz um POST de um evento JSON normalizado para o(s) endpoint(s) HTTPS que você configurar.

Em vez de consultar a API por polling, você se inscreve uma vez e deixa os eventos chegarem até você. Como a Tokeflow normaliza os webhooks de todos os provedores que você orquestra, você escreve um único handler — e não um por provedor — e o formato do evento permanece o mesmo, independentemente de qual adquirente processou a cobrança.

Por que webhooks

Como funciona a entrega

1. Ocorre um evento. Uma transação, reembolso, disputa, método de pagamento ou assinatura muda de estado.
2. A Tokeflow constrói um evento normalizado e o assina com o signing secret do seu endpoint.
3. A Tokeflow faz um POST do evento para cada endpoint correspondente como um corpo de requisição JSON.
4. Seu endpoint responde. Um status 2xx (retornado rapidamente) marca a entrega como bem-sucedida. Qualquer outra coisa dispara uma retentativa.

Configure seus endpoints

Você registra endpoints de webhook no Tokeflow Dashboard durante o onboarding (e a qualquer momento depois disso). Para cada endpoint você fornece:

O envelope do evento

Todo corpo de requisição de webhook compartilha o mesmo formato de nível superior. O campo data.object carrega o recurso ao qual o evento se refere (uma transação, reembolso, assinatura e assim por diante).

{
  "id": "evt_8f3c2a1b9d7e4f60",
  "type": "transaction.authorized",
  "created_at": "2026-01-15T12:30:00.000Z",
  "data": {
    "object": {
      "id": "tx_3n8Q2k1p7w",
      "merchant_id": "mrc_7Yh2Kd9",
      "external_order_id": "order-2026-0042",
      "customer": {
        "id": "cust_5Tg8Lp2",
        "email": "buyer@example.com"
      },
      "previous_status": "pre_authorized",
      "current_status": "authorized",
      "amount_authorized": 15000,
      "amount_captured": 15000,
      "currency": "BRL",
      "changed_at": "2026-01-15T12:30:00.000Z"
    }
  }
}

O que data.object contém

O formato de data.object depende da família de eventos. Consulte Tipos de evento para o catálogo completo e os campos por recurso.

Cabeçalhos da requisição

Cada entrega é um POST HTTP com um corpo JSON e estes cabeçalhos notáveis:

Respondendo a eventos

Seu endpoint deve confirmar o recebimento rapidamente e fazer o trabalho real depois.

• Responda 2xx em poucos segundos. Retorne a resposta assim que tiver persistido o evento com segurança (por exemplo, enfileirado). A Tokeflow trata qualquer 2xx como sucesso.
• Processe de forma assíncrona. Faça o trabalho lento — fulfillment, e-mails, chamadas downstream — fora do ciclo de requisição/resposta para que você nunca corra o risco de um timeout.
• Deduplique por id. Retentativas e entrega at-least-once significam que o mesmo id de evento pode chegar mais de uma vez. Torne o tratamento idempotente: registre os IDs de eventos processados e ignore duplicatas.
• Não dependa da ordem. Os eventos podem chegar fora de ordem, especialmente após uma retentativa. Use os campos de status do recurso (e changed_at) em vez de assumir que a ordem de chegada reflete a sequência real.

// Express example — acknowledge fast, process async.
// Use a raw body parser on this route so signature verification sees exact bytes.
import express from "express";

const app = express();

app.post(
  "/webhooks/tokeflow",
  express.raw({ type: "application/json" }),
  (req, res) => {
    // 1. Verify the signature against the raw body (see Verifying signatures).
    if (!verifyTokeflowSignature(req)) {
      return res.status(400).send("invalid signature");
    }

    const event = JSON.parse(req.body.toString("utf8"));

    // 2. Deduplicate and enqueue for async processing.
    enqueueForProcessing(event); // your job queue

    // 3. Acknowledge immediately.
    return res.status(200).send("ok");
  },
);

Entrega, falhas e retentativas

A Tokeflow registra cada tentativa de entrega para cada endpoint, para que você possa auditar exatamente o que foi enviado e como o seu endpoint respondeu.

Uma entrega é considerada bem-sucedida somente quando o seu endpoint retorna um HTTP 2xx. Uma entrega falha quando retorna um status não-2xx, sofre timeout ou está inacessível. Cada requisição tem um timeout de entrega de 30 segundos — mantenha os handlers bem abaixo disso.

Quando uma entrega falha, a Tokeflow retenta com backoff exponencial:

Depois que o cronograma de retentativas se esgota, a entrega é abandonada e nenhuma outra tentativa é feita. O histórico completo de entrega — códigos de status, trechos de resposta, contagens de tentativas e horário da próxima retentativa — é retido para inspeção. No total, um endpoint que falha em todas as tentativas é reprocessado ao longo de aproximadamente 26 horas antes de a entrega ser abandonada. Cada registro de entrega é carimbado no momento em que foi liquidado — em caso de sucesso ou de abandono — e mantém o código de status HTTP final e o trecho de resposta, de modo que o registro sempre reflete quando a entrega de fato foi concluída, e não quando começou.

Checklist de segurança

• Verifique cada assinatura. Rejeite requisições cujo X-Tokeflow-Signature não valide contra o corpo bruto e o seu secret whsec_.
• Imponha uma tolerância de timestamp. Rejeite eventos cujo timestamp da assinatura esteja fora de uma pequena janela (por exemplo, 5 minutos) para mitigar ataques de replay.
• Use apenas HTTPS. Os endpoints devem ser HTTPS para que payloads e assinaturas sejam protegidos em trânsito.
• Mantenha os secrets no lado do servidor. O signing secret do webhook, assim como as suas chaves de API sk_*, nunca deve aparecer em código de navegador ou de cliente.

Próximos passos

• Tipos de evento — o catálogo completo de tipos de evento e o recurso carregado em data.object.
• Verificando assinaturas — valide X-Tokeflow-Signature passo a passo.
• Autenticação — como funcionam chaves de API, escopos e ambientes.