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

string

obrigatório

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

string

obrigatório

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

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.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.

Próximos Passos

Estrutura do Payload

Entenda a estrutura dos webhooks recebidos

Implementacao

Exemplos de codigo para processar webhooks

Reenviar Webhook

Reenvie webhooks perdidos ou para testes

Cash-In Webhook

Detalhes do webhook de PIX recebido

Introdução

Guias de Integração

Webhooks

Visão Geral

Endpoint

Autenticação

Parâmetros

Exemplo de Request

Exemplo de Response

Comportamento de Upsert

Códigos de Erro

Configurando Múltiplos Eventos

Próximos Passos

Estrutura do Payload

Implementacao

Reenviar Webhook

Cash-In Webhook

​Visão Geral

​Endpoint

​Autenticação

​Parâmetros

​Exemplo de Request

​Exemplo de Response

​Comportamento de Upsert

​Códigos de Erro

​Configurando Múltiplos Eventos

​Próximos Passos

Estrutura do Payload

Implementacao

Reenviar Webhook

Cash-In Webhook

Visão Geral

Endpoint

Autenticação

Parâmetros

Exemplo de Request

Exemplo de Response

Comportamento de Upsert

Códigos de Erro

Configurando Múltiplos Eventos

Próximos Passos