Visão geral
Webhooks são notificações HTTP enviadas pela Alpa Gateway API para sua aplicação quando eventos importantes ocorrem. Isso permite que você reaja em tempo real a mudanças de status, pagamentos confirmados e outros eventos sem precisar fazer polling constante.Pré-requisitos
Antes de começar, você precisa:- Uma conta ativa na Alpa
- Sua API Key configurada (veja Autenticação)
- Um endpoint HTTPS público para receber webhooks
Funcionalidades
- Eventos em tempo real: Receba notificações instantâneas
- Múltiplos eventos: Configure webhooks para diferentes tipos de eventos
- Retry automático: Tentativas automáticas em caso de falha
- Segurança: Assinatura HMAC para validar requisições
- Histórico: Visualize todos os eventos enviados
- Múltiplas URLs: Configure diferentes endpoints para diferentes eventos
Criando uma assinatura de webhook
Requisição Básica
Resposta
X-Webhook-Signature para validação de integridade.
Cabeçalhos HTTP
| Cabeçalho | Descrição |
|---|---|
Content-Type | Sempre application/json |
X-Webhook-Signature | Assinatura HMAC-SHA256 (formato: sha256=ASSINATURA) |
X-Webhook-Event | Tipo do evento disparado |
X-Webhook-Delivery | ID único da entrega (UUID) |
User-Agent | ALPA-Webhook/1.0 |
Eventos Suportados
| Evento | Descrição |
|---|---|
transaction.created | Uma nova transação foi gerada |
transaction.updated | Uma transação teve seus dados atualizados |
transaction.completed | Pagamento confirmado com sucesso |
transaction.failed | Pagamento falhou ou foi recusado |
payment_link.created | Um link de pagamento foi criado |
payment_link.updated | Um link de pagamento foi editado |
balance.updated | O saldo da conta foi alterado |
Eventos de Transação (Transaction)
transaction.created- Transação criadatransaction.updated- Status da transação atualizadotransaction.completed- Pagamento confirmado/concluídotransaction.failed- Pagamento falhou
Eventos de Link de Pagamento
payment_link.created- Link de pagamento criadopayment_link.updated- Link de pagamento atualizado
Exemplo completo
Listando assinaturas
Listar todas as assinaturas
Listar eventos enviados
Atualizando uma assinatura
Deletando uma assinatura
Validando a Assinatura
Para garantir que o webhook foi enviado pela ALPA, você deve validar o headerX-Webhook-Signature.
- Obtenha o corpo bruto (raw body) da requisição.
- Gere um HMAC-SHA256 usando o corpo bruto e o seu
WEBHOOK_SECRET. - Compare o resultado (em hexadecimal) com o valor recebido no header (removendo o prefixo
sha256=).
Exemplo de Validação (Python)
Estrutura do payload
Exemplo: transaction.completed
Exemplo: transaction.failed
🔄 Retry e Confiabilidade
A Alpa tenta entregar webhooks automaticamente:- Primeira tentativa: Imediata
- Retry 1: Após 1 minuto
- Retry 2: Após 5 minutos
- Retry 3: Após 15 minutos
- Retry 4: Após 1 hora
Seu endpoint deve responder com status HTTP 200-299 para confirmar o recebimento. Respostas com erro ou timeout resultarão em retry.
Boas práticas
- Responda rapidamente: Processe webhooks de forma assíncrona quando possível
- Valide a assinatura: Sempre valide o
X-Webhook-Signature - Idempotência: Processe eventos de forma idempotente usando o
iddo evento - Logs: Mantenha logs de todos os webhooks recebidos
- Testes: Use webhooks de teste para validar sua implementação
Testando webhooks
Usando ngrok (Desenvolvimento Local)
Endpoint de Teste
Próximos passos
Referência da API
Veja todos os endpoints disponíveis
Links de Pagamento
Configure webhooks para links de pagamento

