Catálogo de Eventos

Webhooks são disparados quando algo relevante acontece em um pedido, item de envio, transação de pagamento ou saque. Cada UserWebhook cadastrado escolhe um evento (campo event) — para receber vários, cadastre múltiplos webhooks.

Webhook por pedido (postback_url)

Além dos webhooks globais, você pode informar um postback_url ao criar um pedido. Essa URL recebe os eventos order.* e order_item.* daquele pedido, com o mesmo envelope descrito abaixo, somando-se aos webhooks globais (não os substitui). A única diferença: entregas de postback não incluem o header X-Webhook-Signature — proteja a URL com HTTPS + um token secreto no path/query.

Estrutura comum (envelope)

Todo webhook recebido tem o mesmo envelope. Apenas data muda conforme o evento:

{
  "event": "<event.name>",
  "occurred_at": "2026-04-27T13:45:12.123Z",
  "delivery_attempt": 1,
  "data": { }
}

Campo	Tipo	Descrição
event	string	Nome do evento (ex.: order.paid)
occurred_at	ISO 8601 (UTC)	Quando o evento ocorreu no sistema
delivery_attempt	integer	Número da tentativa atual (1 = primeira)
data	object	Payload específico do evento

Headers HTTP enviados

Header	Conteúdo
Content-Type	application/json
User-Agent	Webhooks/1.0
X-Webhook-Event	Nome do evento
X-Webhook-Event-Id	ID único da entrega (ex.: evt_550e8400e29b41d4a716446655440000) — use para idempotência e deduplicação
X-Webhook-Signature	sha256=<hmac_hex> — veja Segurança

Política de retentativas

• Sucesso: qualquer resposta HTTP 2xx encerra a entrega.
• Falha: qualquer outra resposta (incluindo 4xx) ou erro de rede aciona retry com backoff exponencial + jitter.
• Tentativas: até 8 vezes ao longo de horas; após esgotar, a entrega entra em estado dead.
• Reenfileirar manualmente: disponível via painel ou via POST /config/webhooks/{id}/deliveries/{delivery_id}/resend/.

Mascaramento de dados sensíveis

• CPF do comprador: 123.***.***-00
• E-mail: car***@example.com
• Chave PIX: aplicação automática conforme tipo (e-mail, CPF, telefone ou chave aleatória)

---

Eventos disponíveis

Pedido

Evento	Quando dispara
order.created	Pedido criado (status PENDING)
order.paid	Pedido pago (status PAID)
order.expired	Pedido expirado (status EXPIRED)
order.cancelled	Pedido cancelado (status CANCELLED)
order.refunded	Pedido estornado (status REFUNDED)
order.chargeback	Chargeback aberto (status CHARGEBACK)

Envio

Evento	Quando dispara
order_item.shipped	Item enviado (rastreio adicionado)
order_item.delivered	Item entregue

Pagamento

Evento	Quando dispara
payment.pix_qr_code_created	QR Code PIX gerado (transação CRIADA)
payment.approved	Pagamento aprovado (transação APPROVED)
payment.refunded	Pagamento estornado (transação REFUNDED)

Saque

Evento	Quando dispara
withdrawal.requested	Saque solicitado (status PENDING)
withdrawal.approved	Saque aprovado
withdrawal.denied	Saque negado
withdrawal.processing	Saque em processamento
withdrawal.paid	Saque concluído com sucesso
withdrawal.failed	Saque falhou

---

Exemplos de payload

order.paid

{
  "event": "order.paid",
  "occurred_at": "2026-04-27T13:45:12.123Z",
  "delivery_attempt": 1,
  "data": {
    "order": {
      "uuid": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "status": "PAID",
      "method": "PIX",
      "gross_amount": 15000,
      "shipping_amount": 500,
      "discount_amount": 0,
      "fee_amount": 149,
      "net_amount": 14851,
      "created_at": "2026-04-27T13:30:00Z",
      "paid_at": "2026-04-27T13:45:12Z"
    },
    "seller": { "name": "João Vendedor" },
    "affiliate": { "name": "Maria Afiliada" },
    "customer": {
      "name": "Carlos Comprador",
      "tax_id": "123.***.***-00",
      "tax_id_type": "CPF",
      "email": "car***@example.com"
    },
    "items": [
      {
        "product_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "product_name": "Produto A",
        "quantity": 2,
        "unit_amount": 7000,
        "line_total_amount": 14000
      }
    ]
  }
}

order_item.shipped

{
  "event": "order_item.shipped",
  "occurred_at": "2026-04-28T10:12:33.456Z",
  "delivery_attempt": 1,
  "data": {
    "order": { "uuid": "9f1c2d3e-...", "status": "PAID" },
    "item": {
      "product_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "product_name": "Produto A",
      "quantity": 2,
      "shipping_status": "SHIPPED",
      "tracking_code": "BR123456789CD",
      "shipped_at": "2026-04-28T10:12:33Z",
      "delivered_at": null
    },
    "seller": { "name": "João Vendedor" }
  }
}

payment.approved

{
  "event": "payment.approved",
  "occurred_at": "2026-04-27T13:45:12.123Z",
  "delivery_attempt": 1,
  "data": {
    "transaction": {
      "id": "1f2c3d4e-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
      "method": "PIX",
      "status": "APPROVED",
      "gross_amount": 15000,
      "fee_amount": 149,
      "net_amount": 14851,
      "approved_at": "2026-04-27T13:45:12Z"
    },
    "order": { "uuid": "9f1c2d3e-...", "status": "PAID" },
    "seller": { "name": "João Vendedor" } 
  }
}

withdrawal.paid

{
  "event": "withdrawal.paid",
  "occurred_at": "2026-04-29T16:20:05.789Z",
  "delivery_attempt": 1,
  "data": {
    "withdrawal": {
      "uuid": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
      "status": "PAID",
      "gross_amount": 14851,
      "requested_at": "2026-04-29T15:00:00Z",
      "decided_at": "2026-04-29T16:20:05Z"
    },
    "bank_data": {
      "pix_key": "car***@example.com",
      "pix_key_type": "email"
    },
    "seller": { "name": "João Vendedor" }
  }
}

informação

Valores possíveis de pix_key_type: email, cpf, phone, random.

---

Boas práticas no receptor

1. Verifique a assinatura HMAC antes de processar — veja Segurança.
2. Deduplique pelo header X-Webhook-Event-Id — em casos raros (retries que demoram) o mesmo evento pode chegar duas vezes; persista o valor do header recebido e ignore o duplicado.
3. Responda 2xx em até ~1s — não processe o payload na mesma request; coloque numa fila interna e processe assíncrono.
4. Trate todos os status — não confie só no event para decidir se é "paid". Use os campos de status dentro de data para o estado real.
5. Mantenha o secret seguro — ele só é exibido uma vez na criação. Se vazar, gere um novo webhook (a rotação aposenta o secret antigo).