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 API > Webhook URL. Após configurar, você pode validar se sua aplicação está respondendo corretamente clicando no botão Enviar Teste (ping), que disparará um evento ping para a URL informada. O painel exibirá o histórico completo dos webhooks disparados, incluindo carga útil (payload), código de status e tempo de resposta.

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 os seguintes cabeçalhos em todas as requisições:

X-NomadPay-Event: <evento>
X-Signature: <hmac-sha256-hex>
Content-Type: application/json

O valor de X-Signature é um HMAC SHA256 do corpo (payload) da requisição — excluindo o campo signature presente no body — gerado usando o seu Webhook Secret (disponível no seu dashboard). O campo signature também é incluído no próprio body do payload com o mesmo valor.

⚠️ API REST x Webhooks

A NomadPay possui dois mecanismos diferentes de integração:

API REST	Webhooks
Utilizada quando sua aplicação faz uma requisição para a NomadPay.	Utilizado quando a NomadPay envia automaticamente um evento para sua URL configurada.
Você inicia a comunicação.	A NomadPay inicia a comunicação.
Exemplo: GET /charges/:id	Exemplo: evento charge.paid

Esses formatos não são iguais.

A resposta de um endpoint REST possui uma estrutura própria.

Os Webhooks possuem outro formato, contendo informações do evento ocorrido.

Sempre utilize o campo event para identificar qual evento foi recebido.

Cada evento representa uma mudança de estado da transação e deve ser tratado individualmente pela sua aplicação.

Exemplo de resposta da API REST

{
  "id": "chg_xxxxx",
  "amount": 100.50,
  "description": "Pedido #123",
  "status": "PAID",
  "pix_code": "...",
  "created_at": "...",
  "paid_at": "..."
}

Exemplo de Webhook

{
  "event": "charge.paid",
  "event_id": "evt_xxxxxxxxx",
  "timestamp": "2026-07-08T16:30:00.000Z",
  "charge_id": "chg_xxxxx",
  "status": "PAID",
  "amount": 100.50,
  "net_amount": 98.40,
  "e2e_id": "E123...",
  "endToEndId": "E123...",
  "txid": "TX123...",
  "signature": "..."
}

O payload acima é enviado automaticamente para a URL de Webhook cadastrada no painel da NomadPay.

Quando cada Webhook é enviado

Evento	Quando é disparado
charge.paid	Quando uma cobrança muda para PAID.
withdrawal.pending	Assim que o saque é solicitado.
withdrawal.processing	Quando o saque começa a ser processado.
withdrawal.paid	Quando o saque é concluído com sucesso.
withdrawal.failed	Quando o saque falha.
withdrawal.cancelled	Quando o saque é cancelado.

Eventos Disponíveis

charge.paid

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

// Headers:
// X-NomadPay-Event: charge.paid
// X-Signature: <hmac-sha256-hex>
// Content-Type: application/json

// Payload:
{
  "event": "charge.paid",
  "event_id": "evt_a1b2c3d4e5f6g7h8i9j0",
  "timestamp": "2026-06-27T12:05:00.000Z",
  "charge_id": "chg_xxxxxxx",
  "status": "PAID",
  "amount": 100.50,
  "net_amount": 100.50,
  "e2e_id": "E9999999920260627120500000000000",
  "endToEndId": "E9999999920260627120500000000000",
  "txid": "chg_xxxxxxx",
  "signature": "<hmac-sha256-hex>"
}

Status possíveis da cobrança:

Status	Descrição
PENDING	Aguardando pagamento.
PAID	Paga com sucesso. O webhook charge.paid é disparado neste momento.
EXPIRED	Expirada sem pagamento.
CANCELLED	Cancelada.

O webhook charge.paid é enviado somente quando a cobrança muda para PAID.

---

Eventos de Saque (PIX Out)

Ao longo do ciclo de vida de um saque, sua aplicação receberá webhooks em tempo real. Cada mudança de status gera um evento distinto.

Eventos disparados

Evento	Quando é enviado
withdrawal.pending	Disparado imediatamente após a criação do saque.
withdrawal.processing	Disparado quando o saque sai da fila e começa a ser processado no banco.
withdrawal.paid	Disparado quando o PIX é liquidado com sucesso na conta informada.
withdrawal.failed	Disparado quando ocorre um erro bancário (ex: chave PIX inválida). O campo reason conterá o motivo.
withdrawal.cancelled	Disparado caso a operação seja cancelada. O campo reason pode conter o motivo.

Status possíveis do saque

Status	Descrição
PENDING	O saque entrou na fila de processamento e o valor foi reservado.
PROCESSING	O saque está sendo ativamente processado com o banco.
PAID	O saque foi liquidado com sucesso na conta informada.
FAILED	Ocorreu uma falha no processamento bancário. O valor é estornado.
CANCELLED	A operação foi cancelada. O valor é estornado.

withdrawal.pending

// Headers:
// X-NomadPay-Event: withdrawal.pending
// X-Signature: <hmac-sha256-hex>
// Content-Type: application/json

// Payload:
{
  "event": "withdrawal.pending",
  "event_id": "evt_a1b2c3d4e5f6g7h8i9j0",
  "timestamp": "2026-06-27T17:00:00.000Z",
  "company_id": "comp_xxxxxxx",
  "withdrawal_id": "wd_a1b2c3d4e5f6",
  "withdrawal_reference": "WDR_A1B2C3D4E5F67890",
  "status": "PENDING",
  "amount": 250.00,
  "retry_count": 0,
  "signature": "<hmac-sha256-hex>"
}

withdrawal.processing

// Headers:
// X-NomadPay-Event: withdrawal.processing
// X-Signature: <hmac-sha256-hex>
// Content-Type: application/json

// Payload:
{
  "event": "withdrawal.processing",
  "event_id": "evt_b2c3d4e5f6g7h8i9j0k1",
  "timestamp": "2026-06-27T17:02:00.000Z",
  "company_id": "comp_xxxxxxx",
  "withdrawal_id": "wd_a1b2c3d4e5f6",
  "withdrawal_reference": "WDR_A1B2C3D4E5F67890",
  "status": "PROCESSING",
  "amount": 250.00,
  "retry_count": 0,
  "signature": "<hmac-sha256-hex>"
}

withdrawal.paid

// Headers:
// X-NomadPay-Event: withdrawal.paid
// X-Signature: <hmac-sha256-hex>
// Content-Type: application/json

// Payload:
{
  "event": "withdrawal.paid",
  "event_id": "evt_c3d4e5f6g7h8i9j0k1l2",
  "timestamp": "2026-06-27T17:05:00.000Z",
  "company_id": "comp_xxxxxxx",
  "withdrawal_id": "wd_a1b2c3d4e5f6",
  "withdrawal_reference": "WDR_A1B2C3D4E5F67890",
  "status": "PAID",
  "amount": 250.00,
  "retry_count": 0,
  "signature": "<hmac-sha256-hex>"
}

withdrawal.failed

// Headers:
// X-NomadPay-Event: withdrawal.failed
// X-Signature: <hmac-sha256-hex>
// Content-Type: application/json

// Payload:
{
  "event": "withdrawal.failed",
  "event_id": "evt_d4e5f6g7h8i9j0k1l2m3",
  "timestamp": "2026-06-27T17:05:00.000Z",
  "company_id": "comp_xxxxxxx",
  "withdrawal_id": "wd_a1b2c3d4e5f6",
  "withdrawal_reference": "WDR_A1B2C3D4E5F67890",
  "status": "FAILED",
  "amount": 250.00,
  "retry_count": 0,
  "reason": "Chave PIX inválida ou inexistente.",
  "signature": "<hmac-sha256-hex>"
}

withdrawal.cancelled

// Headers:
// X-NomadPay-Event: withdrawal.cancelled
// X-Signature: <hmac-sha256-hex>
// Content-Type: application/json

// Payload:
{
  "event": "withdrawal.cancelled",
  "event_id": "evt_e5f6g7h8i9j0k1l2m3n4",
  "timestamp": "2026-06-27T17:05:00.000Z",
  "company_id": "comp_xxxxxxx",
  "withdrawal_id": "wd_a1b2c3d4e5f6",
  "withdrawal_reference": "WDR_A1B2C3D4E5F67890",
  "status": "CANCELLED",
  "amount": 250.00,
  "retry_count": 0,
  "reason": "Operação cancelada pelo administrador.",
  "signature": "<hmac-sha256-hex>"
}