Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usealpa.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Eventos disponíveis

Configure seus webhooks para receber notificações dos eventos relevantes para sua integração. Cada evento entrega um payload JSON com os dados do objeto afetado.

​
Transações

EventoQuando disparado
transaction.createdNova transação criada (status PENDING)
transaction.updatedStatus da transação foi alterado
transaction.completedPagamento confirmado e saldo creditado (PAID)
transaction.failedPagamento falhou (FAILED)
EventoQuando disparado
payment_link.createdNovo link de pagamento criado
payment_link.updatedLink de pagamento atualizado (ex: estoque zerado, desativado)

​
Saldo

EventoQuando disparado
balance.updatedSaldo da carteira atualizado (crédito ou débito)

​
Assinaturas

EventoQuando disparado
subscription.createdNova assinatura criada
subscription.activatedPrimeira cobrança aprovada — assinatura ativa
subscription.charge_failedCobrança recorrente falhou — status muda para PAST_DUE
subscription.cancelledAssinatura cancelada (pelo assinante ou pelo merchant)
subscription.pausedAssinatura pausada pelo assinante
subscription.resumedAssinatura retomada após pausa

​
Formato do payload

Todos os eventos seguem a mesma estrutura de envelope: 
{
  "event": "transaction.completed",
  "timestamp": "2026-05-25T14:30:00.000Z",
  "data": { }
}

​
Exemplo: transaction.completed

{
  "event": "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"
  }
}

​
Exemplo: subscription.charge_failed

{
  "event": "subscription.charge_failed",
  "timestamp": "2026-05-25T10:00:00.000Z",
  "data": {
    "subscriptionId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "planName": "Plano Mensal Premium",
    "clientEmail": "maria@example.com",
    "amountCents": 9900,
    "failureReason": "insufficient_funds",
    "retryAt": "2026-05-28T10:00:00.000Z"
  }
}

​
Verificar assinatura do webhook

Todos os eventos incluem o header X-Webhook-Signature com um HMAC-SHA256 do payload, assinado com o segredo configurado na assinatura. 
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
Sempre valide a assinatura antes de processar o evento. Ignore requests sem o header ou com assinatura inválida.

​
Listar eventos recebidos

Use o endpoint de eventos para consultar o histórico de webhooks disparados: 
curl --request GET \
  --url 'https://alpa-sistema-api.onrender.com/api/v1/webhooks/events?limit=20' \
  --header 'Authorization: Bearer SUA_API_KEY'

Criar assinatura de webhook

Configure quais eventos receber e para qual URL.

Referência de webhooks

Visão geral do sistema de webhooks.