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 assinaturasVerificando 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
| Evento | Descricao |
|---|---|
| payment.created | Pagamento criado |
| payment.processing | Pagamento em processamento |
| payment.completed | Pagamento concluido com sucesso |
| payment.failed | Pagamento falhou |
| token.created | Token criado |
| token.used | Token utilizado |
| token.expired | Token expirou |
| pix.payment.completed | Pagamento PIX concluido |
| pix.refund.completed | Devolucao 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:
| Tentativa | Delay |
|---|---|
| 1 | Imediato |
| 2 | 5 minutos |
| 3 | 30 minutos |
| 4 | 2 horas |
| 5 | 24 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