Webhooks
Receba notificações em tempo real quando eventos ocorrerem em sua organização. Webhooks permitem que você construa integrações reativas que respondem imediatamente a digitalizações de QR code e outros eventos.
Tempo real
Receba notificações instantâneas quando eventos ocorrerem, sem necessidade de polling
Seguro
As assinaturas HMAC verificam se os webhooks vêm da iloveQR
Confiável
Tentativas automáticas com retrocesso exponencial para entregas falhadas
Configurando Webhooks
Configure webhooks através do painel ou da API para começar a receber eventos.
Criar um endpoint de webhook
Configure um endpoint HTTPS em seu servidor para receber cargas úteis de webhook.
Registrar o webhook
Adicione a URL do seu endpoint e selecione quais eventos assinar.
Verificar assinaturas
Implemente a verificação de assinatura para garantir que os payloads sejam autênticos.
curl -X POST \
"https://api.iloveqr.com/api/v1/organizations/org_abc123/webhooks" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-server.com/webhooks/iloveqr",
"events": ["qr.scanned", "qr.created", "qr.updated"],
"secret": "your_webhook_secret"
}'Eventos de Webhook
Inscreva-se nos eventos que você precisa. Cada tipo de evento tem uma estrutura de payload específica.
Eventos de QR Code
qr.createdUm novo código QR foi criadoqr.updatedUm código QR foi atualizadoqr.deletedUm código QR foi excluídoqr.scannedUm código QR foi escaneadoqr.archivedUm código QR foi arquivadoqr.restoredUm código QR foi restaurado do arquivoEventos de Assinatura
subscription.createdUma nova assinatura foi criadasubscription.updatedUma assinatura foi atualizadasubscription.cancelledUma assinatura foi canceladasubscription.payment_succeededUm pagamento foi bem-sucedidosubscription.payment_failedUm pagamento falhouEventos da Equipe
member.joinedUm membro entrou na organizaçãomember.leftUm membro deixou a organizaçãomember.role_changedO papel de um membro foi alteradoCarga Útil do Webhook
Todos os payloads de webhook seguem uma estrutura consistente com metadados de evento e dados.
{
"id": "evt_1a2b3c4d5e6f",
"event": "qr.scanned",
"createdAt": "2024-01-15T14:30:00Z",
"organizationId": "org_abc123",
"data": {
"qrCodeId": "qr_xyz789",
"qrCodeName": "Product Landing Page",
"shortCode": "xyz789",
"destinationUrl": "https://example.com/product",
"scan": {
"id": "scan_123abc",
"timestamp": "2024-01-15T14:30:00Z",
"location": {
"country": "US",
"city": "New York",
"latitude": 40.7128,
"longitude": -74.0060
},
"device": {
"type": "mobile",
"os": "iOS",
"browser": "Safari"
},
"isUnique": true
}
}
}{
"id": "evt_7g8h9i0j1k2l",
"event": "qr.created",
"createdAt": "2024-01-15T10:00:00Z",
"organizationId": "org_abc123",
"data": {
"qrCode": {
"id": "qr_newcode",
"type": "URL",
"name": "New Campaign QR",
"shortUrl": "https://ilqr.co/newcode",
"destinationUrl": "https://example.com/campaign",
"createdBy": "user_abc123"
}
}
}Verificando Webhooks
Sempre verifique as assinaturas do webhook para garantir que o payload veio do iloveQR e não foi adulterado durante o trânsito.
Cabeçalho de Assinatura
Cada solicitação de webhook inclui um cabeçalho X-Webhook-Signature contendo uma assinatura HMAC-SHA256 do corpo da solicitação.
const crypto = require('crypto');
function verifyWebhookSignature(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
// In your webhook handler
app.post('/webhooks/iloveqr', (req, res) => {
const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);
if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
// Process the webhook
const event = req.body;
console.log('Received event:', event.event);
res.status(200).send('OK');
});import hmac
import hashlib
def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(
secret.encode(),
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)
# In your Flask handler
@app.route('/webhooks/iloveqr', methods=['POST'])
def handle_webhook():
signature = request.headers.get('X-Webhook-Signature')
payload = request.get_data()
if not verify_webhook_signature(payload, signature, WEBHOOK_SECRET):
return 'Invalid signature', 401
event = request.get_json()
print(f"Received event: {event['event']}")
return 'OK', 200Melhores Práticas
Responda rapidamente
Retorne uma resposta 2xx em até 5 segundos. Processar webhooks de forma assíncrona se o seu processamento levar mais tempo.
Lidar com duplicatas
Armazene o ID do evento e verifique se há duplicatas. Webhooks podem ser entregues mais de uma vez em casos raros.
Use HTTPS
Sempre use endpoints HTTPS. Não entregamos webhooks para URLs HTTP.
Falhas de monitor
Configure a monitoração para falhas na entrega do webhook. Verifique os logs do webhook no painel para depuração.
Política de Retentativa
Se seu endpoint retornar um erro ou não responder, nós automaticamente tentamos entregar novamente com um retrocesso exponencial:
| Tentativa | Atraso |
|---|---|
| 1ª tentativa | 1 minuto |
| 2ª tentativa | 5 minutos |
| 3ª tentativa | 30 minutos |
| 4ª tentativa | 2 horas |
| 5ª tentativa (final) | 24 horas |
Nota: Após 5 tentativas falhadas, o webhook é marcado como falhado e paramos de tentar novamente. Você receberá uma notificação por e-mail sobre a falha.
Próximos Passos
Pronto para começar? Explore mais recursos: