Webhooks - Alpa Gateway API

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 se uma transação já foi confirmada. Isso é lento e ineficiente. Com webhooks, a Alpa avisa você imediatamente quando o pagamento é confirmado, entregando os dados do evento. Assim você pode atualizar o status de um pedido, liberar acesso a um produto, enviar e-mails de confirmação ou registrar movimentações financeiras — de forma automática.

Ambientes (Desenvolvimento vs Produção)

Ambientes da Alpa

Webhooks criados com chaves de Desenvolvimento recebem eventos simulados
Webhooks criados com chaves de Produção recebem eventos reais

Formato do payload

Todos os eventos compartilham o mesmo envelope:

{
  "id": "f7c1b2a0-...",
  "type": "transaction.completed",
  "data": { },
  "timestamp": "2026-05-25T14:30:00.000Z",
  "subscription": {
    "id": "sub_abc123",
    "url": "https://meusite.com/webhooks/alpa"
  }
}

O campo type identifica o evento. O campo data carrega os dados do objeto afetado.

Exemplo: `transaction.completed`

{
  "id": "f7c1b2a0-...",
  "type": "transaction.completed",
  "timestamp": "2026-05-25T14:30:00.000Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "PAID",
    "amountCents": 9900,
    "paymentMethod": "PIX",
    "clientEmail": "joao@example.com",
    "createdAt": "2026-05-25T14:29:00.000Z",
    "paidAt": "2026-05-25T14:30:00.000Z"
  }
}

Dados sensíveis: documentos (CPF/CNPJ) são mascarados nos payloads. Para cartão, apenas os últimos 4 dígitos e a bandeira são enviados.

Eventos suportados

Evento (`type`)	Quando é disparado
`transaction.created`	Nova transação criada (status `PENDING`)
`transaction.updated`	Status da transação alterado
`transaction.completed`	Pagamento confirmado e saldo creditado (`PAID`)
`transaction.failed`	Pagamento falhou (`FAILED`)
`transaction.refunded`	Reembolso concluído
`payment_link.created`	Novo link de pagamento criado
`payment_link.updated`	Link de pagamento atualizado
`balance.updated`	Saldo da carteira atualizado
`subscription.cancelled`	Assinatura cancelada
`kyc.submitted` / `kyc.approved` / `kyc.rejected`	Mudanças no status de KYC
`advance.created` / `advance.approved` / `advance.rejected`	Antecipações
`withdrawal.requested` / `withdrawal.completed` / `withdrawal.failed`	Saques

Segurança: assinatura HMAC

Cada webhook enviado pela Alpa inclui uma assinatura no header X-Webhook-Signature, gerada com HMAC-SHA256 sobre o corpo bruto da requisição e codificada em hexadecimal (prefixada por sha256=). Seu backend deve recalcular a assinatura e comparar com a recebida usando comparação em tempo constante.

import crypto from "node:crypto";

export function verifyAlpaSignature(
  rawBody: string,
  signatureFromHeader: string, // valor do header X-Webhook-Signature
  secret: string
): boolean {
  const received = signatureFromHeader.replace(/^sha256=/, "");
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Use o corpo bruto (raw body) para validar — não o JSON re-serializado. Sempre valide a assinatura antes de processar o evento.

Usando um dos SDKs oficiais? Eles já trazem verifyWebhookSignature(payload, signature, secret) pronto.

Criando uma assinatura de webhook

Defina seu endpoint

Crie um endpoint HTTPS público que receberá as notificações.

Requisitos do endpoint

Deve ser HTTPS (HTTP não é aceito)
Deve responder 200 OK dentro de 10 segundos
Deve aceitar requisições POST com body JSON

Crie a assinatura via API

curl -X POST "https://alpa-sistema-api.onrender.com/api/v1/webhooks/subscriptions" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meusite.com/webhooks/alpa",
    "events": ["transaction.completed", "withdrawal.completed"]
  }'

A resposta inclui o secret da assinatura apenas na criação — guarde-o com segurança.

Valide os eventos recebidos

Implemente a validação HMAC no seu endpoint para garantir que os eventos são legítimos.

Boas práticas

Recomendações importantes

Use HTTPS em todos os webhooks
Valide a assinatura HMAC em cada requisição recebida
Processe cada evento uma única vez (idempotência via campo id)
Responda 200 OK somente após concluir o processamento
Não valide o payload inteiro com schemas rígidos — novos campos podem ser adicionados sem aviso prévio

Precisa de ajuda?

Nossa equipe pode te ajudar. Contate-nos: suporte@usealpa.com

​Por que usar webhooks?

​Ambientes (Desenvolvimento vs Produção)

Ambientes da Alpa

​Formato do payload

​Exemplo: transaction.completed

​Eventos suportados

​Segurança: assinatura HMAC

​Criando uma assinatura de webhook

Requisitos do endpoint

​Boas práticas

Recomendações importantes

Precisa de ajuda?

Por que usar webhooks?

Ambientes (Desenvolvimento vs Produção)

Formato do payload

Exemplo: `transaction.completed`

Eventos suportados

Segurança: assinatura HMAC

Criando uma assinatura de webhook

Boas práticas