Tipos de Eventos - Alpa Gateway API

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

Evento	Quando disparado
`transaction.created`	Nova transação criada (status `PENDING`)
`transaction.updated`	Status da transação foi alterado
`transaction.completed`	Pagamento confirmado e saldo creditado (`PAID`)
`transaction.failed`	Pagamento falhou (`FAILED`)

Links de pagamento

Evento	Quando disparado
`payment_link.created`	Novo link de pagamento criado
`payment_link.updated`	Link de pagamento atualizado (ex: estoque zerado, desativado)

Saldo

Evento	Quando disparado
`balance.updated`	Saldo da carteira atualizado (crédito ou débito)

Assinaturas

Evento	Quando disparado
`subscription.created`	Nova assinatura criada
`subscription.activated`	Primeira cobrança aprovada — assinatura ativa
`subscription.charge_failed`	Cobrança recorrente falhou — status muda para `PAST_DUE`
`subscription.cancelled`	Assinatura cancelada (pelo assinante ou pelo merchant)
`subscription.paused`	Assinatura pausada pelo assinante
`subscription.resumed`	Assinatura retomada após pausa

Formato do payload

Todos os eventos seguem a mesma estrutura de envelope. O campo type identifica o evento:

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

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"
  }
}

Exemplo: `subscription.charge_failed`

{
  "id": "f7c1b2a0-...",
  "type": "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 received = signature.replace(/^sha256=/, '');
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  const a = Buffer.from(received);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

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.

Deletar Assinatura de Webhook

​Eventos disponíveis

​Transações

​Links de pagamento

​Saldo

​Assinaturas

​Formato do payload

​Exemplo: transaction.completed

​Exemplo: subscription.charge_failed

​Verificar assinatura do webhook

​Listar eventos recebidos

Criar assinatura de webhook

Referência de webhooks

Eventos disponíveis

Transações

Links de pagamento

Saldo

Assinaturas

Formato do payload

Exemplo: `transaction.completed`

Exemplo: `subscription.charge_failed`

Verificar assinatura do webhook

Listar eventos recebidos