Entenda como o sistema de webhooks da Worldfy funciona e como receber notificações em tempo real sobre eventos da sua conta.
Webhooks são notificações HTTP enviadas automaticamente pela Worldfy para a sua aplicação quando eventos importantes acontecem, como a captura de uma cobrança, um estorno ou um chargeback.
Em vez de consultar a API periodicamente para verificar mudanças (polling), você configura endpoints de webhook e a Worldfy envia um POST com os dados do evento assim que ele ocorre.
HTTP POST para todos os endpoints ativos que estão inscritos nesse evento2xxVocê pode configurar quantos endpoints quiser. Cada endpoint possui:
| Campo | Descrição |
|---|---|
| URL | A URL que receberá as notificações via HTTP POST |
| Eventos | Lista de eventos que este endpoint recebe (ex: charge.captured, charge.refunded) |
| Secret | Chave HMAC-SHA256 exclusiva para verificar a autenticidade das notificações |
| Status | active (recebe notificações) ou paused (temporariamente desativado) |
Cada endpoint tem seu próprio secret. Isso permite que você integre com múltiplos sistemas, cada um com sua própria chave de verificação.
Todos os webhooks seguem a mesma estrutura de envelope, com o campo de dados variando conforme o tipo de evento:
{
"id": "uuid-do-delivery-log",
"event": "charge.captured",
"charge": { "..." },
"occurred_at": "2026-02-24T10:00:00.000Z"
}{
"id": "uuid-do-delivery-log",
"event": "merchant.approved",
"merchant": { "..." },
"occurred_at": "2026-03-30T14:00:00.000Z"
}{
"id": "uuid-do-delivery-log",
"event": "withdrawal.completed",
"withdrawal": { "..." },
"occurred_at": "2026-03-30T14:05:00.000Z"
}| Campo | Tipo | Descrição |
|---|---|---|
id | string | Identificador único da entrega (delivery log) |
event | string | Nome do evento (ex: charge.captured, merchant.approved, withdrawal.completed) |
charge | object | Dados da cobrança (presente em eventos charge.*) |
merchant | object | Dados da conta/merchant (presente em eventos merchant.*) |
withdrawal | object | Dados do saque (presente em eventos withdrawal.*) |
occurred_at | string | Data/hora em que o evento ocorreu (ISO 8601) |
Cada notificação inclui os seguintes headers:
| Header | Descrição |
|---|---|
Content-Type | application/json |
X-Worldfy-Signature | Assinatura HMAC-SHA256 do payload (ex: sha256=abc123...) |
X-Worldfy-Event | Nome do evento (ex: charge.captured) |
X-Worldfy-Delivery-Id | ID único da entrega |
User-Agent | Worldfy-Postback/1.0 |
Eventos de criação, captura, estorno e falha de cobranças
Eventos de solicitação, aprovação, processamento e conclusão de saques
Além dos eventos de cobrança e saque, a Worldfy também emite eventos de conta (merchant), descritos abaixo.
Eventos relacionados à análise e aprovação da conta do merchant.
| Evento | Descrição |
|---|---|
merchant.approved | Conta aprovada e habilitada para transacionar |
merchant.rejected | Conta rejeitada na análise |
{
"id": "uuid-do-delivery-log",
"event": "merchant.approved",
"merchant": {
"id": "m1e2r3c4-h5a6-7890-ntid-000000000001",
"trade_name": "Loja do João",
"legal_name": "João Silva ME",
"tax_id": "12345678000199",
"email": "contato@lojadojoao.com",
"status": "active",
"review_notes": null,
"reviewed_at": "2026-03-30T14:00:00.000Z",
"created_at": "2026-03-25T10:00:00.000Z",
"updated_at": "2026-03-30T14:00:00.000Z"
},
"occurred_at": "2026-03-30T14:00:00.000Z"
}Campo do objeto merchant | Tipo | Descrição |
|---|---|---|
id | string | ID do merchant |
trade_name | string | Nome fantasia |
legal_name | string | Razão social |
tax_id | string | CPF ou CNPJ |
email | string | E-mail da conta |
status | string | Status atual da conta |
review_notes | string | null | Motivo da rejeição (quando aplicável) |
reviewed_at | string | null | Data/hora da análise (ISO 8601) |
created_at | string | Data/hora da criação (ISO 8601) |
updated_at | string | Data/hora da última atualização (ISO 8601) |
Em decisões automáticas, o corpo pode incluir os campos adicionais decided_by_system (boolean) e decision_context (metadados da decisão).