Skip to main content
Pense nos webhooks como “mensagens enviadas pela Alpa para o seu sistema”, sem que você precise ficar consultando a API o tempo todo.

Por que usar webhooks?

Sem webhooks, sua aplicação teria que perguntar para a API a cada segundo:
“Essa transação já foi confirmada?”
Com webhooks, a Alpa avisa você imediatamente:
“A transação foi confirmada. Aqui estão os dados.”
Assim você pode:
  • Atualizar o status de um pedido
  • Liberar acesso a um produto digital
  • Enviar e-mails automáticos de confirmação
  • Registrar movimentações financeiras
Tudo isso de forma automática, sem fazer seu cliente esperar.

Como funciona na prática?

  1. Você cria um endpoint no seu sistema Ex.: https://meusite.com.br/webhooks/alpa
  2. Você cadastra esse endpoint via API ou Dashboard
  3. Sempre que algo importante acontece, como uma transação paga:
    • A Alpa envia um POST para a sua URL
    • O POST contém o evento (ex: transaction.completed)
    • Seu sistema processa esse evento e responde 200 OK

Segurança dos webhooks

Toda requisição enviada inclui dois mecanismos de segurança:

Assinatura HMAC

Cada webhook inclui o header X-Webhook-Signature: sha256=... gerado com HMAC-SHA256. Sempre valide essa assinatura antes de processar o evento — garante que a requisição foi enviada pela Alpa e que o corpo não foi alterado.

Headers de identificação

Além da assinatura, cada entrega inclui:
  • X-Webhook-Event — tipo do evento (ex: transaction.completed)
  • X-Webhook-Delivery — UUID único da entrega
  • User-Agent: ALPA-Webhook/1.0

Validação da assinatura


Estrutura do payload

Todos os webhooks compartilham o mesmo envelope:

Eventos suportados

EventoQuando é disparado
transaction.createdNova transação criada
transaction.completedPagamento confirmado
transaction.failedPagamento falhou
transaction.updatedStatus da transação atualizado
payment_link.createdNovo link de pagamento criado
payment_link.updatedLink de pagamento atualizado
balance.updatedSaldo da conta alterado

Payloads por evento

Transações

Disparado quando um pagamento é confirmado.

Criando uma assinatura de webhook

1

Crie uma assinatura via API

2

Implemente o endpoint

Seu endpoint deve responder 200 OK em até 10 segundos. Respostas fora desse prazo são tratadas como falha e a entrega será retentada automaticamente.
3

Valide a assinatura

Use o header X-Webhook-Signature para verificar que a requisição veio da Alpa. Veja os exemplos de código acima.

Boas práticas

  • Use HTTPS em todos os endpoints de webhook
  • Valide sempre a assinatura HMAC antes de processar
  • Registre cada evento recebido — processe cada um uma única vez (idempotência)
  • Responda 200 OK somente após concluir o processamento
  • Implemente retentativas com idempotência no seu sistema
  • Não valide o schema completo do payload — mudanças futuras não devem quebrar seu endpoint

Precisa de ajuda?

Nossa equipe está disponível para ajudar. Entre em contato: suporte@usealpa.com