Configurar Webhook

Configure webhooks para receber notificacoes em tempo real sobre transferencias, recebimentos, reembolsos e erros de Cash Out.

Visao Geral

A API de Cash Out disponibiliza 4 endpoints de webhook, cada um para um tipo de evento diferente. Voce pode configurar cada um de forma independente, com URLs, headers e comportamentos distintos.

Endpoint	Descricao
`POST /api/v2/webhooks/transfer`	Notificacoes de transferencias concluidas ou falhas
`POST /api/v2/webhooks/receive`	Notificacoes de Pix recebidos
`POST /api/v2/webhooks/refund`	Notificacoes de reembolsos
`POST /api/v2/webhooks/cashout`	Notificacoes de erros de Cash Out

Todos os endpoints de webhook utilizam a mesma estrutura de body (uri, email, method, enabled, pauseOnFail, headers). A diferenca esta no tipo de evento que cada um notifica.

1. Webhook de Transferencia

POST/api/v2/webhooks/transfer

Configura o webhook para receber notificacoes quando transferencias Pix (Cash Out) forem concluidas ou falharem.

Base URL: https://pagamentos.basspago.com.br

Headers

Header	Valor	Descricao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2
`Content-Type`	application/json

Parametros do Body

Nome	Tipo	Obrigatorio	Descricao
`uri`	string	Obrigatorio	URL do webhook que recebera as notificacoes. Deve ser HTTPS.
`enabled`	boolean	Obrigatorio	Habilita (true) ou desabilita (false) o webhook.
`email`	string	Opcional	Email para receber alertas em caso de falhas consecutivas no envio do webhook.
`method`	string	Opcional	Metodo HTTP usado para enviar as notificacoes: POST, GET ou PUT. Padrao: POST.
`pauseOnFail`	boolean	Opcional	Se true, pausa o webhook automaticamente apos falhas consecutivas. Padrao: true.
`headers`	object	Opcional	Headers customizados enviados junto com cada notificacao do webhook.

Exemplo de Request

{
  "uri": "https://your-api.com/webhooks/transfer",
  "email": "alerts@example.com",
  "method": "POST",
  "enabled": true,
  "pauseOnFail": true,
  "headers": {
    "X-Webhook-Secret": "your-secret-key"
  }
}

Exemplo de Response

{
  "id": "wh_transfer_abc123",
  "uri": "https://your-api.com/webhooks/transfer",
  "email": "alerts@example.com",
  "method": "POST",
  "enabled": true,
  "pauseOnFail": true,
  "headers": {
    "X-Webhook-Secret": "your-secret-key"
  },
  "createdAt": "2026-04-08T12: 00:00Z"
}

Exemplos de Codigo

curl -X POST \
  https://pagamentos.basspago.com.br/api/v2/webhooks/transfer \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "uri": "https://your-api.com/webhooks/transfer",
    "email": "alerts@example.com",
    "method": "POST",
    "enabled": true,
    "pauseOnFail": true,
    "headers": {
      "X-Webhook-Secret": "your-secret-key"
    }
  }'

2. Webhook de Recebimento

POST/api/v2/webhooks/receive

Configura o webhook para receber notificacoes quando um Pix for recebido na conta.

Base URL: https://pagamentos.basspago.com.br

Headers

Header	Valor	Descricao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2
`Content-Type`	application/json

Parametros do Body

Nome	Tipo	Obrigatorio	Descricao
`uri`	string	Obrigatorio	URL do webhook que recebera as notificacoes de Pix recebidos.
`enabled`	boolean	Obrigatorio	Habilita (true) ou desabilita (false) o webhook.
`email`	string	Opcional	Email para alertas de falha.
`method`	string	Opcional	Metodo HTTP: POST, GET ou PUT. Padrao: POST.
`pauseOnFail`	boolean	Opcional	Pausa o webhook apos falhas consecutivas.
`headers`	object	Opcional	Headers customizados enviados com as notificacoes.

Exemplo de Request

{
  "uri": "https://your-api.com/webhooks/receive",
  "enabled": true,
  "pauseOnFail": true,
  "headers": {
    "X-Webhook-Secret": "your-secret-key"
  }
}

Exemplo de Response

{
  "id": "wh_receive_def456",
  "uri": "https://your-api.com/webhooks/receive",
  "enabled": true,
  "pauseOnFail": true,
  "headers": {
    "X-Webhook-Secret": "your-secret-key"
  },
  "createdAt": "2026-04-08T12: 00:00Z"
}

3. Webhook de Reembolso

POST/api/v2/webhooks/refund

Configura o webhook para receber notificacoes sobre reembolsos de transacoes Pix.

Base URL: https://pagamentos.basspago.com.br

Headers

Header	Valor	Descricao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2
`Content-Type`	application/json

Parametros do Body

Nome	Tipo	Obrigatorio	Descricao
`uri`	string	Obrigatorio	URL do webhook que recebera as notificacoes de reembolso.
`enabled`	boolean	Obrigatorio	Habilita (true) ou desabilita (false) o webhook.
`email`	string	Opcional	Email para alertas de falha.
`method`	string	Opcional	Metodo HTTP: POST, GET ou PUT. Padrao: POST.
`pauseOnFail`	boolean	Opcional	Pausa o webhook apos falhas consecutivas.
`headers`	object	Opcional	Headers customizados enviados com as notificacoes.

Exemplo de Request

{
  "uri": "https://your-api.com/webhooks/refund",
  "enabled": true,
  "headers": {
    "X-Webhook-Secret": "your-secret-key"
  }
}

Exemplo de Response

{
  "id": "wh_refund_ghi789",
  "uri": "https://your-api.com/webhooks/refund",
  "enabled": true,
  "headers": {
    "X-Webhook-Secret": "your-secret-key"
  },
  "createdAt": "2026-04-08T12: 00:00Z"
}

4. Webhook de Erros Cash Out

POST/api/v2/webhooks/cashout

Configura o webhook para receber notificacoes sobre erros ocorridos em operacoes de Cash Out.

Base URL: https://pagamentos.basspago.com.br

Headers

Header	Valor	Descricao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2
`Content-Type`	application/json

Parametros do Body

Nome	Tipo	Obrigatorio	Descricao
`uri`	string	Obrigatorio	URL do webhook que recebera as notificacoes de erros de Cash Out.
`enabled`	boolean	Obrigatorio	Habilita (true) ou desabilita (false) o webhook.
`email`	string	Opcional	Email para alertas de falha.
`method`	string	Opcional	Metodo HTTP: POST, GET ou PUT. Padrao: POST.
`pauseOnFail`	boolean	Opcional	Pausa o webhook apos falhas consecutivas.
`headers`	object	Opcional	Headers customizados enviados com as notificacoes.

Exemplo de Request

{
  "uri": "https://your-api.com/webhooks/cashout",
  "email": "ops@example.com",
  "enabled": true,
  "pauseOnFail": true,
  "headers": {
    "X-Webhook-Secret": "your-secret-key"
  }
}

Exemplo de Response

{
  "id": "wh_cashout_jkl012",
  "uri": "https://your-api.com/webhooks/cashout",
  "email": "ops@example.com",
  "enabled": true,
  "pauseOnFail": true,
  "headers": {
    "X-Webhook-Secret": "your-secret-key"
  },
  "createdAt": "2026-04-08T12: 00:00Z"
}

Gerenciamento de Webhooks

Alem de criar webhooks, voce pode listar, consultar e remover webhooks configurados.

GET/api/v2/webhooks

Lista todos os webhooks configurados na conta.

Base URL: https://pagamentos.basspago.com.br

Headers

Header	Valor	Descricao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Exemplo de Response

[
  {
    "id": "wh_transfer_abc123",
    "type": "transfer",
    "uri": "https://your-api.com/webhooks/transfer",
    "email": "alerts@example.com",
    "method": "POST",
    "enabled": true,
    "pauseOnFail": true,
    "headers": {
      "X-Webhook-Secret": "your-secret-key"
    },
    "createdAt": "2026-04-08T12: 00:00Z"
  },
  {
    "id": "wh_receive_def456",
    "type": "receive",
    "uri": "https://your-api.com/webhooks/receive",
    "enabled": true,
    "pauseOnFail": false,
    "headers": {},
    "createdAt": "2026-04-08T12: 05:00Z"
  }
]

Exemplos de Codigo

curl -X GET \
  https://pagamentos.basspago.com.br/api/v2/webhooks \
  -H 'Authorization: Bearer {access_token}'

GET/api/v2/webhooks/{webhookId}

Consulta os detalhes de um webhook especifico pelo seu ID.

Base URL: https://pagamentos.basspago.com.br

Headers

Header	Valor	Descricao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Parametros de Rota

Nome	Tipo	Descricao
`webhookId`	string	ID do webhook retornado na criacao.

Exemplo de Response

{
  "id": "wh_transfer_abc123",
  "type": "transfer",
  "uri": "https://your-api.com/webhooks/transfer",
  "email": "alerts@example.com",
  "method": "POST",
  "enabled": true,
  "pauseOnFail": true,
  "headers": {
    "X-Webhook-Secret": "your-secret-key"
  },
  "createdAt": "2026-04-08T12: 00:00Z"
}

Exemplos de Codigo

curl -X GET \
  https://pagamentos.basspago.com.br/api/v2/webhooks/wh_transfer_abc123 \
  -H 'Authorization: Bearer {access_token}'

DELETE/api/v2/webhooks/{webhookId}

Remove um webhook configurado. Retorna HTTP 204 (sem conteudo) em caso de sucesso.

Base URL: https://pagamentos.basspago.com.br

Headers

Header	Valor	Descricao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Parametros de Rota

Nome	Tipo	Descricao
`webhookId`	string	ID do webhook a ser removido.

Exemplo de Response

// HTTP 204 No Content
// (resposta sem corpo / empty response body)

Exemplos de Codigo

curl -X DELETE \
  https://pagamentos.basspago.com.br/api/v2/webhooks/wh_transfer_abc123 \
  -H 'Authorization: Bearer {access_token}'

Mecanismo de Retentativa

Quando o seu endpoint nao responde com HTTP 200, a Versell reenvia a notificacao seguindo o cronograma de retentativas abaixo. Apos 15 falhas consecutivas, o webhook e automaticamente desabilitado.

Tentativa	Intervalo	Descricao
1-3	2 min	Retentativa a cada 2 minutos
4-8	15 min	Retentativa a cada 15 minutos
9-15	60 min	Retentativa a cada 60 minutos
15+	--	Webhook desabilitado automaticamente

Se o campo pauseOnFail estiver habilitado e o email estiver configurado, voce recebera um alerta por email antes do webhook ser desabilitado. Reative o webhook manualmente apos corrigir o endpoint.

Boas Praticas

1.Responda com 200 rapidamente — Retorne HTTP 200 imediatamente ao receber o webhook. Processe os dados de forma assincrona para evitar timeouts e retentativas desnecessarias.
2.Use headers customizados para seguranca — Configure um header secreto (ex: X-Webhook-Secret) e valide-o em cada requisicao recebida para garantir a autenticidade.
3.Trate duplicatas — Webhooks podem ser enviados mais de uma vez devido ao mecanismo de retentativa. Use o endToEndId ou transferId como chave de idempotencia.
4.Habilite pauseOnFail — Configure pauseOnFail: true e um email de alerta para ser notificado antes que o webhook seja desabilitado apos 15 falhas.
5.Configure todos os tipos necessarios — Cada tipo de evento tem um endpoint separado. Configure ao menos /webhooks/transfer para acompanhar o status das suas transferencias.