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 cadastrados diretamente no painel 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, em formato 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 está disponível apenas para webhooks cadastrados no painel. Webhooks enviados para uma URL informada dinamicamente via notificationUrl não incluem a assinatura X-Signature.

A validação por assinatura é opcional, porém fortemente recomendada sempre que o webhook for configurado pelo painel, 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
  }
}