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 a nova URL configurada.
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
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
Tipo de evento para receber notificações.
Valores possíveis:
cash_in- PIX recebidocash_out- PIX enviadorefund_in- Estorno de recebimento (devolução solicitada)refund_out- Devolução recebida
Headers customizados para autenticação do seu endpoint (máximo 5).
Cada item deve ter:
key: Nome do headervalue: 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.public.firebanking.com.br/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.public.firebanking.com.br/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.public.firebanking.com.br/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"
}Comportamento de Upsert
Se já existir um webhook configurado para o mesmo eventType, ele será atualizado com a nova URL e headers. Não é criado um webhook duplicado.
Ao atualizar um webhook existente, os headers anteriores são substituídos pelos novos. Se você não enviar headers, os headers anteriores serão removidos.
Códigos de Erro
| Código | Descrição |
|---|---|
| 400 | URL inválida (não é HTTPS), tipo de evento inválido, ou mais de 5 headers |
| 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'];
for (const eventType of eventTypes) {
await fetch('https://api.public.firebanking.com.br/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.