Configurar Webhooks via API

Visão Geral

A API de configuração de webhooks permite que você defina programaticamente onde sua aplicação receberá notificações de eventos PIX. Isso elimina a necessidade de contato com o suporte para configurar webhooks.

Mudanças na configuração de webhooks são aplicadas imediatamente. Transações subsequentes usarão as URLs configuradas.

Endpoint

POST /api/webhooks

Autenticação

Requer token Bearer da conta (Account Token) no header Authorization.

Authorization: Bearer {account_token}

O token deve ser obtido através do endpoint de autenticação usando seu certificado de cliente.

Parâmetros

stringobrigatorio

URL HTTPS do seu endpoint de webhook.

Requisitos:

Deve usar protocolo HTTPS (HTTP não é aceito)
Deve ser uma URL válida e acessível

Exemplo: https://api.example.com/webhooks/pix

stringobrigatorio

Tipo de evento para receber notificações.

Valores possíveis:

cash_in - PIX recebido
cash_out - PIX enviado
refund_in - Estorno de recebimento (devolução solicitada)
refund_out - Devolução recebida
med_created - MED (Mecanismo Especial de Devolução) aberto contra uma transação recebida
med_accepted - Solicitação de devolução MED aprovada
med_rejected - Solicitação de devolução MED rejeitada

array

Headers customizados para autenticação do seu endpoint (máximo 5).

Cada item deve ter:

key: Nome do header
value: Valor do header

Headers bloqueados (nao permitidos):

host
content-length
connection
transfer-encoding
content-type
user-agent

Exemplo de Request

curl -X POST https://api-pay.brasilbitco.in/api/webhooks \
  -H "Authorization: Bearer {account_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/pix",
    "eventType": "cash_in",
    "headers": [
      {
        "key": "Authorization",
        "value": "Bearer my-secret-token"
      },
      {
        "key": "X-Webhook-Secret",
        "value": "abc123"
      }
    ]
  }'

const response = await fetch('https://api-pay.brasilbitco.in/api/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accountToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://api.example.com/webhooks/pix',
    eventType: 'cash_in',
    headers: [
      { key: 'Authorization', value: 'Bearer my-secret-token' },
      { key: 'X-Webhook-Secret', value: 'abc123' },
    ],
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    'https://api-pay.brasilbitco.in/api/webhooks',
    headers={
        'Authorization': f'Bearer {account_token}',
        'Content-Type': 'application/json',
    },
    json={
        'url': 'https://api.example.com/webhooks/pix',
        'eventType': 'cash_in',
        'headers': [
            {'key': 'Authorization', 'value': 'Bearer my-secret-token'},
            {'key': 'X-Webhook-Secret', 'value': 'abc123'},
        ],
    },
)

print(response.json())

Exemplo de Response

{
  "success": true,
  "message": "Webhook configurado com sucesso"
}

Múltiplas URLs por Evento

Você pode cadastrar até 3 URLs ativas para o mesmo eventType. Cada chamada a este endpoint adiciona uma nova URL ao evento — as demais URLs já cadastradas continuam ativas e não são substituídas.

Se você reenviar uma URL que já está cadastrada para aquele eventType, ela é atualizada (headers e version), sem criar um webhook duplicado.

Quando o evento ocorre, a notificação é enviada em fan-out para todas as URLs ativas cadastradas naquele eventType. Cada URL possui sua própria entrega, retentativa e idempotência — uma falha em uma URL não afeta as demais.

Ao recadastrar uma URL já existente, omitir headers ou version preserva os valores anteriores. Enviar o campo explicitamente substitui o valor anterior desse campo — os demais campos omitidos continuam preservados.

Códigos de Erro

Código	Descrição
400	URL inválida (não é HTTPS), tipo de evento inválido, mais de 5 headers, ou mais de 3 URLs ativas por evento
401	Token não fornecido ou inválido
404	Conta não encontrada
500	Erro interno ao configurar webhook

Configurando Múltiplos Eventos

Para receber notificações de múltiplos tipos de eventos, faça uma chamada para cada tipo:

const eventTypes = [
  'cash_in',
  'cash_out',
  'refund_in',
  'refund_out',
  'med_created',
  'med_accepted',
  'med_rejected',
];

for (const eventType of eventTypes) {
  await fetch('https://api-pay.brasilbitco.in/api/webhooks', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accountToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      url: 'https://api.example.com/webhooks/pix',
      eventType,
      headers: [
        { key: 'X-Webhook-Secret', value: 'abc123' },
      ],
    }),
  });
}

Você pode usar a mesma URL para todos os tipos de evento e diferenciar pelo campo type no payload do webhook.

Configurar Webhooks via API

Visão Geral

Endpoint

Autenticação

Parâmetros

Exemplo de Request

Exemplo de Response

Múltiplas URLs por Evento

Códigos de Erro

Configurando Múltiplos Eventos

Próximos Passos

Estrutura do Payload

Implementacao

Reenviar Webhook

Cash-In Webhook

Webhooks MED

Nesta página