Descrição

O webhook de transferência é enviado automaticamente sempre que o status do saque for alterado, permitindo que o sistema do integrador acompanhe todo o ciclo da transferência, desde a criação até a conclusão ou falha.

As notificações são enviadas via requisições HTTP no método POST, utilizando o formato JSON.

Padrão de Timezone

Todos os campos de data e hora enviados nos webhooks utilizam o padrão ISO 8601 no timezone UTC (UTC+00:00), garantindo consistência independentemente do fuso horário do integrador. Para evitar divergências causadas por horários locais ou horário de verão, recomenda-se manter os valores em UTC para armazenamento e processamento, realizando a conversão para o fuso horário local apenas no nível de apresentação ao usuário final.

Validação Opcional do Webhook

Para aumentar a segurança, os webhooks podem incluir uma assinatura enviada no header X-Signature: <assinatura-em-base64>, permitindo validar a autenticidade da notificação recebida. Essa assinatura é gerada pela plataforma utilizando HMAC com SHA-256 sobre o corpo do webhook (JSON), usando um segredo compartilhado WEBHOOK_SECRET e codificada em Base64. O integrador pode reproduzir o mesmo cálculo em seu sistema utilizando o mesmo segredo e o payload recebido; se a assinatura gerada for igual à enviada no header, o webhook é considerado legítimo e íntegro. Caso sejam diferentes, a requisição pode ter sido alterada ou não ter sido enviada pela plataforma. Essa validação é opcional, porém fortemente recomendada para garantir maior segurança na comunicação.

Endpoint de Notificação

Caso informado, o webhook será enviado para a URL configurada no campo notificationUrl.

O endpoint deve estar acessível publicamente e responder com HTTP 200 para confirmar o recebimento da notificação.

Além disso, as notificações de transferência também podem ocorrer via webhook in-bound, configurado diretamente no painel do gateway. Nesse modelo, o endpoint é previamente cadastrado e será acionado automaticamente a cada mudança de status da transferência.

Status da Transferência

Os possíveis valores para o campo status são:

• IN_QUEUE – Transferência criada e aguardando processamento.
• IN_ANALYSIS – Transferência em análise.
• APPROVED – Transferência aprovada (não paga).
• PROCESSING – Transferência em processamento.
• COMPLETED – Transferência concluída com sucesso (paga).
• REFUSED – Transferência recusada.
• FAILED – Falha no processamento da transferência.

Dados PIX

As informações da chave PIX de destino estão presentes no objeto data:

• pixKey – Chave PIX utilizada na transferência.
• pixKeyType – Tipo da chave PIX (CPF, CNPJ, EMAIL, PHONE, EVP, COPYPASTE).

Formato do Payload

Abaixo está um exemplo do payload enviado no webhook de uma transferência via PIX.

{
  "id": "pay_test_8f3k2m9xq7a1b4c6",
  "amount": 5000,
  "method": "PIX",
  "currency": "BRL",
  "status": "IN_QUEUE",
  "message": "",
  "externalRef": "order_test_1234",
  "notificationUrl": "https://example-webhook.test/notifications",
  "approvedAt": null,
  "refusedAt": null,
  "cancelledAt": null,
  "paidAt": null,
  "createdAt": "2026-01-19T17:17:34.295Z",
  "updatedAt": "2026-01-19T17:17:34.295Z",
  "data": {
    "method": "PIX",
    "pixKey": "pix_test_123e4567-e89b-12d3-a456-426614174000",
    "pixKeyType": "EVP",
    "e2e": null
  }
}