LLiccenDocs

Receber eventos

Envie webhook_url na criação da cobrança ou da transferência e receba os eventos dela, sem cadastrar nada antes.

É o jeito recomendado de integrar. Cada cobrança e cada transferência carrega a URL que deve ser avisada, então o seu sistema decide o destino na hora de criar o recurso: um pedido da loja A vai para o backend da loja A, um repasse vai para o financeiro, sem configuração na dashboard.

Como usar

Campos na criação

webhook_url
stringopcional
URL http(s) pública que recebe os POSTs. Até 2048 caracteres.
webhook_secret
stringopcional
Assina as entregas para essa URL com o header X-Webhook-Signature.
cURL
curl -X POST https://api.transakto.io/v1/charges \
  -H "x-api-key: sk_live_..." \
  -H "Idempotency-Key: pedido-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4990,
    "reference": "pedido-1042",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@exemplo.com.br",
      "document": "123.456.789-09"
    },
    "webhook_url": "https://meusistema.com.br/hooks/pagamentos",
    "webhook_secret": "um-segredo-bem-longo"
  }'

Funciona igual em POST /v1/payouts. A URL volta no campo webhook_url das respostas, para você conferir o que ficou gravado. O segredo nunca volta.

O que chega

Todos os eventos daquele recurso, do created ao desfecho: para uma cobrança Pix, charge.pix.created, charge.pix.emitted e depois charge.pix.paid (ou failed, refunded e os demais). Não há lista de eventos para escolher: se aconteceu com o recurso, a URL fica sabendo.

O corpo, os headers e a assinatura são os mesmos de qualquer entrega. Veja Eventos para o formato e Assinatura para validar o X-Webhook-Signature. O campo reference vem em todos os eventos, então dá para achar o pedido sem guardar o id da cobrança.

Sem webhook_secret não há assinatura, e quem descobrir a URL consegue simular um pagamento confirmado. Em produção, mande sempre o segredo.

Regras

A URL precisa ser http ou https e apontar para um host público. localhost, IPs de rede privada e endereços de link local são recusados na criação com 422 e INVALID_WEBHOOK_URL, antes de qualquer cobrança ser emitida. Para testar na sua máquina, exponha a porta com um túnel (ngrok, cloudflared) e use a URL pública dele.

A URL fica fixa no recurso: não dá para trocar depois de criado. Se o seu endereço mudar, as cobranças novas já saem com o novo, e as entregas antigas podem ser reenviadas pela dashboard.

Entregas e retentativas

Responda com qualquer status 2xx em até 10 segundos. Outra resposta, timeout ou erro de conexão conta como falha, e a entrega é repetida em 1 minuto, 5 minutos, 15 minutos, 1 hora, 3 horas, 6 horas e 12 horas: são 8 tentativas no total, ao longo de cerca de 22 horas. Depois disso a entrega fica como falha e pode ser reenviada pela dashboard.

Toda repetição leva o mesmo id de evento. Use esse id para ignorar o que já processou. As entregas saem em paralelo e não há garantia de ordem entre eventos: confie no status do recurso que vem no corpo, não na ordem de chegada.

Junto com endpoints cadastrados

Se a sua aplicação também tem endpoints cadastrados em /v1/webhooks, eles continuam recebendo os eventos que assinaram. As duas formas somam: o webhook_url do recurso recebe tudo daquele recurso, e o endpoint cadastrado recebe os eventos escolhidos de todos os recursos.

Quando o webhook_url é exatamente a mesma URL de um endpoint cadastrado que já assina o evento, a entrega sai uma vez só, assinada com o segredo do endpoint cadastrado.

AnteriorDados da contaPróximaEndpoints cadastrados