Webhooks

Requisição

O que chega na sua URL quando um evento dispara — cabeçalhos, campos e exemplos para copiar.

Formato da requisição

Todas as entregas são POST com corpo JSON (UTF-8). Dois cabeçalhos ajudam a identificar a entrega; o token de autenticação fica no próprio JSON.

POST

POST https://sua-api.com/alocis/webhooks
Content-Type: application/json
X-Webhook-Id: whdlv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Webhook-Event: TRANSACTION_PAID

Cabeçalho	Descrição
`X-Webhook-Id`	ID da entrega (whdlv_…). Use para idempotência no seu lado.
`X-Webhook-Event`	Nome do evento, igual ao campo type do JSON.
`token` (no JSON)	Token da conta (whtok_…). Compare com o valor do painel antes de processar.

A prova de URL (criação ou troca de endereço) expira em 10 s. Entregas de eventos reais usam timeout de 30 s por tentativa.

Envelope do payload

Todos os eventos compartilham a mesma estrutura. Campos nulos são omitidos do JSON para reduzir tamanho.

TRANSACTION_PAID

{
  "id": "whdlv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "type": "TRANSACTION_PAID",
  "createdAt": "2026-01-15T14:22:11.000Z",
  "workspaceId": "wks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token": "whtok_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": {
    "transaction": {
      "id": "txn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "status": "PAID",
      "amount": 9900,
      "currency": "BRL",
      "paymentMethod": "PIX"
    },
    "products": [{ "id": "prd_xxx", "name": "Curso completo" }],
    "customer": {
      "name": "Maria Silva",
      "email": "[email protected]",
      "phone": "+5511999999999"
    }
  }
}

O objeto data reúne o contexto do fato. Campos opcionais aparecem conforme o tipo de evento:

Campo	Descrição
`data.transaction`	Transação afetada (id, status, amount em centavos, currency, paymentMethod).
`data.subscription`	Assinatura e itens; em mudanças, objetos billingDayChange, cycleChange, itemsChange ou scheduledFor.
`data.pix` / `data.boleto`	Somente em TRANSACTION_AWAITING_PAYMENT: código Pix ou URL/linha digitável do boleto.
`data.refundRequest`	Somente em TRANSACTION_REFUND_REQUESTED: pedido feito pelo comprador no painel do comprador.
`data.abandonedCart`	Somente em ABANDONED_CART: produtos, bumps selecionados e dados capturados no checkout.

Exemplos por tipo de evento

Os dados abaixo são simulados, mas seguem o formato real. Campos que não se aplicam ao evento simplesmente não aparecem no JSON.

Evento de verificação

endpoint.test

{
  "id": "whurl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "type": "endpoint.test",
  "createdAt": "2026-01-15T14:20:00.000Z",
  "workspaceId": "wks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token": "whtok_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": { "ok": true }
}

SUBSCRIPTION_CREATED

Assinatura

{
  "id": "whdlv_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
  "type": "SUBSCRIPTION_CREATED",
  "createdAt": "2026-02-01T10:00:00.000Z",
  "workspaceId": "wks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token": "whtok_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": {
    "subscription": {
      "id": "sub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "status": "ACTIVE",
      "billingInterval": "MONTHLY",
      "billingDay": 10,
      "items": [{ "productId": "prd_xxx", "name": "Plano Pro", "quantity": 1, "amount": 4900 }]
    },
    "customer": { "name": "João Souza", "email": "[email protected]" },
    "products": [{ "id": "prd_xxx", "name": "Plano Pro" }]
  }
}

ABANDONED_CART

Carrinho

{
  "id": "whdlv_zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",
  "type": "ABANDONED_CART",
  "createdAt": "2026-02-10T18:45:00.000Z",
  "workspaceId": "wks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token": "whtok_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": {
    "abandonedCart": {
      "products": [{ "id": "prd_aaa", "name": "E-book" }],
      "capturedEmail": "[email protected]"
    },
    "products": [{ "id": "prd_aaa", "name": "E-book" }]
  }
}

Catálogo de eventos

Cadastre apenas os eventos que sua integração precisa. Os nomes são estáveis e em SCREAMING_SNAKE_CASE.

Transações

Evento	Quando dispara
`TRANSACTION_PAID`	Transação confirmada como paga.
`TRANSACTION_FAILED`	Pagamento recusado ou falhou (exceto expiração de Pix/boleto).
`TRANSACTION_EXPIRED`	Pix ou boleto expirou sem confirmação.
`TRANSACTION_AWAITING_PAYMENT`	Pix ou boleto gerado e aguardando pagamento (inclui dados de pagamento em data).
`TRANSACTION_REFUNDED`	Estorno total ou parcial concluído pelo merchant.
`TRANSACTION_REFUND_REQUESTED`	Comprador solicitou estorno pelo painel do comprador (ainda não processado pelo merchant).
`TRANSACTION_CHARGEBACK`	Chargeback confirmado.
`TRANSACTION_CHARGEBACK_REQUESTED`	Disputa ou chargeback em aberto.

Assinaturas

Evento	Quando dispara
`SUBSCRIPTION_CREATED`	Nova assinatura criada.
`SUBSCRIPTION_BILLING_DAY_CHANGED`	Dia de cobrança alterado.
`SUBSCRIPTION_CYCLE_CHANGED`	Intervalo de cobrança alterado.
`SUBSCRIPTION_ITEMS_CHANGED`	Itens da assinatura alterados.
`SUBSCRIPTION_CANCELLED`	Assinatura cancelada de forma efetiva.
`SUBSCRIPTION_PAST_DUE`	Assinatura em atraso.
`SUBSCRIPTION_REGULARIZED`	Assinatura regularizada após atraso.
`SUBSCRIPTION_CANCELLATION_SCHEDULED`	Cancelamento agendado para o fim do período.
`SUBSCRIPTION_ITEMS_CHANGE_SCHEDULED`	Troca de itens agendada para data futura.

Checkout

Evento	Quando dispara
`ABANDONED_CART`	Comprador abandonou o checkout (dados capturados e produtos selecionados).

Ordem entre eventos

Um mesmo checkout pode gerar mais de um evento (por exemplo pagamento e criação de assinatura). Cada um é uma entrega separada — a ordem de chegada não é garantida. Projete sua integração para lidar com isso.