Webhooks

A NomadPay envia webhooks (callbacks) para o seu sistema sempre que há uma atualização importante no status de uma cobrança ou de um saque.

Configuração

Você pode configurar a sua Webhook URL no painel da NomadPay, acessando Configurações > Webhooks. Ao receber uma requisição da NomadPay, a sua aplicação deve retornar o status HTTP 200 OK.

Segurança (Assinatura)

Para garantir que a requisição partiu legitimamente da NomadPay, nós enviamos o cabeçalho X-Signature em todas as requisições. Essa assinatura é um HMAC SHA256 do corpo (payload) da requisição, gerado usando o seu Webhook Secret (que pode ser obtido no seu dashboard).

Eventos Disponíveis

CHARGE_PAID

Enviado quando uma cobrança PIX é paga com sucesso.

// Headers:
// X-NomadPay-Event: CHARGE_PAID
// X-Signature: <hmac-sha256-signature>

// Payload:
{
  "id": "chg_1234567890",
  "amount": 100.50,
  "description": "Pedido #1234",
  "status": "PAID"
}

WITHDRAWAL_APPROVED

Enviado quando o seu saque (Cash Out) foi processado e transferido com sucesso para a chave PIX solicitada.

// Headers:
// X-NomadPay-Event: WITHDRAWAL_APPROVED
// X-Signature: <hmac-sha256-signature>

// Payload:
{
  "id": "wd_1234567890",
  "amount": 250.50,
  "pix_key_type": "CPF",
  "pix_key": "12345678909",
  "status": "APPROVED",
  "created_at": "2026-06-27T10:00:00.000Z"
}