Webhooks e Callbacks

Configure webhooks para receber notificacoes em tempo real sobre eventos do ecossistema Axon.

Configurando webhooks

Configure seus endpoints de webhook no Dashboard ou via API:

create-webhook.jsjavascript
const response = await fetch('https://api.axon.com/v1/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.AXON_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://your-app.com/webhooks/axon',
    events: [
      'payment.completed',
      'payment.failed',
      'token.created',
      'token.expired',
    ],
    description: 'Webhook principal de producao',
  }),
});

const webhook = await response.json();
// Guarde o webhook.secret para verificar assinaturas

Verificando assinaturas

Sempre verifique a assinatura do webhook para garantir autenticidade:

verify-webhook.jsjavascript
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(typeof payload === 'string' ? payload : JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

// No seu endpoint
app.post('/webhooks/axon', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-axon-signature'];
  const timestamp = req.headers['x-axon-timestamp'];

  // Verificar timestamp para prevenir replay attacks
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    return res.status(401).json({ error: 'Timestamp expired' });
  }

  // Verificar assinatura
  const signedPayload = `${timestamp}.${req.body}`;
  if (!verifyWebhookSignature(signedPayload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);
  // Processar evento...

  res.status(200).json({ received: true });
});

Seguranca

Nunca processe webhooks sem verificar a assinatura. Webhooks nao verificados podem ser falsificados por atacantes.

Eventos disponiveis

EventoDescricao
payment.createdPagamento criado
payment.processingPagamento em processamento
payment.completedPagamento concluido com sucesso
payment.failedPagamento falhou
token.createdToken criado
token.usedToken utilizado
token.expiredToken expirou
pix.payment.completedPagamento PIX concluido
pix.refund.completedDevolucao PIX concluida

Formato do payload

webhook-payload.jsonjson
{
  "id": "evt_abc123def456",
  "type": "payment.completed",
  "created_at": "2024-01-15T10:30:00Z",
  "api_version": "2024-01-01",
  "data": {
    "object": {
      "id": "pay_xyz789",
      "amount": 150.00,
      "currency": "BRL",
      "status": "completed",
      "metadata": {
        "order_id": "order_123"
      }
    },
    "previous_attributes": {
      "status": "processing"
    }
  }
}

Retries automaticos

Webhooks que falham sao retentados automaticamente:

TentativaDelay
1Imediato
25 minutos
330 minutos
42 horas
524 horas

Apos 5 tentativas sem sucesso, o webhook e marcado como falho. Voce pode reenviar manualmente pelo Dashboard.

Boas praticas

  • Responda rapidamente (menos de 5 segundos)
  • Processe eventos de forma assincrona (filas)
  • Implemente idempotencia (eventos podem ser reenviados)
  • Sempre verifique a assinatura
  • Use HTTPS com certificado valido