Webhooks

Webhooks são notificações HTTP POST enviadas para o seu servidor quando ocorrem eventos importantes em nossa plataforma. Eles permitem que você seja notificado automaticamente sobre mudanças de status em pedidos, saques e outras operações.

Eventos Suportados

Nossa plataforma envia webhooks para os seguintes eventos:

order.created: Pedido gerado
order.paid: Pedido pago
order.failed: Pedido falho (método de pagamento cartão de crédito)
order.refunded: Pedido reembolsado
withdrawal.confimed: Saque foi processado e confirmado

Configuração

Você pode configurar a URL de recebimento de webhooks no seu painel de controle da plataforma. A URL deve ser acessível publicamente via HTTPS.

Para desenvolvimento local, você pode usar ferramentas como ngrok ou similar para expor seu servidor local publicamente.

Formato do Webhook

Exemplo: Confirmação de Pagamento

Quando um pedido é pago, você receberá uma requisição POST no formato:

{
  "event": "order.paid",
  "data": {
    "affiliate_id": null,
    "amount": "12",
    "buyer": null,
    "created_at": "2026-02-03T22:43:36.306Z",
    "external_id": null,
    "fees": { "fixed": "1", "variable": "0.12" },
    "id": "2763cf1a-2263-4125-b151-72f88ffa108c",
    "net_amount": "10.88",
    "offer": null,
    "payment_method": "pix",
    "product": null,
    "seller_id": "ad5c4916-79e6-4c98-b9d0-3462118b4cb3",
    "shipping_amount": "0",
    "splits": [
      {
        "fixedFee": "6",
        "sourceSellerId": "ad5c4916-79e6-4c98-b9d0-3462118b4cb3",
        "sourceSubAccountId": null,
        "splitAmount": "6",
        "targetSellerId": null,
        "targetSubAccountId": "sb_01kg68ckswecy8txkyjf8h1w48",
        "variableFee": "0"
      }
    ],
    "status": {
      "detail": "00020101021226830014br.gov.bcb.pix2561qrcode.a55scd.com.br/pix/7101de04-1c55-49e5-8969-eff466f9cb655204000053039865802BR591455.202.855LTDA6008SaoPaulo62070503***63045CAF",
      "name": "pending"
    },
    "subAccountId": null,
    "tracking": {
      "ref": null,
      "sck": null,
      "src": null,
      "utm_campaign": null,
      "utm_content": null,
      "utm_id": null,
      "utm_medium": null,
      "utm_source": null,
      "utm_term": null
    },
    "type": "sale"
  }
}

Exemplo: Saque Concluído

Quando um saque é concluído:

{
  "event": "withdraw.confimed",
  "data": {
    "id": "wt_01kg68ckswecy8txkyjf8h1w48",
    "status": "confirmed",
    "pix_key": "c10d6a4e-c4ad-4d27-b820-8d410236a311",
    "total_amount": "164.40",
    "net_amount": "163.40",
    "variable_fee": "0",
    "fixed_fee": "1",
    "created_at": "2026-02-05T00:08:52.660Z",
    "confirmed_at": "2026-02-05T00:08:52.932Z"
  }
}

Segurança

Autenticação via Header Authorization

Caso configurado na plataforma, as requisições de webhook podem incluir um header Authorization:

Authorization: Bearer SEU_TOKEN_WEBHOOK

IMPORTANTE: Sempre valide a origem dos webhooks antes de processá-los. Nunca processe webhooks sem validação adequada, pois isso pode expor sua aplicação a ataques.

Processamento de Webhooks

Boas Práticas

Responda rapidamente: Sempre retorne um status HTTP 200 o mais rápido possível (dentro de 2-3 segundos)
Processe assincronamente: Para operações demoradas, processe o webhook em background e retorne 204
Idempotência: Implemente verificação de duplicatas usando o order_id ou withdrawal_id
Logs: Mantenha logs de todos os webhooks recebidos para debugging

Próximos Passos

Configure seu endpoint de webhook na plataforma
Implemente a validação de segurança
Teste com eventos reais

Webhooks

On this page