Webhooks - Documentação da API - iloveQR

Documentação da API

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 escaneamentos de QR codes e outros eventos.

Em tempo real

Receba notificações instantaneamente quando eventos ocorrerem, sem necessidade de polling

Seguro

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 API para começar a receber eventos.

Crie um endpoint de webhook

Configure um endpoint HTTPS em seu servidor para receber cargas úteis de webhook.

Registre o webhook

Adicione a URL do seu endpoint e selecione quais eventos assinar.

Verifique assinaturas

Implemente a verificação de assinatura para garantir que as cargas úteis sejam autênticas.

Registrar Webhook

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 carga útil específica.

Eventos de QR Code

qr.createdUm novo QR code foi criado

qr.updatedUm QR code foi atualizado

qr.deletedUm QR code foi excluído

qr.scannedUm QR code foi escaneado

qr.archivedUm QR code foi arquivado

qr.restoredUm QR code foi restaurado do arquivo

Eventos de Assinatura

subscription.createdUma nova assinatura foi criada

subscription.updatedUma assinatura foi atualizada

subscription.cancelledUma assinatura foi cancelada

subscription.payment_succeededUm pagamento foi bem-sucedido

subscription.payment_failedUm pagamento falhou

Eventos de Equipe

member.joinedUm membro entrou na organização

member.leftUm membro saiu da organização

member.role_changedO papel de um membro foi alterado

Webhook Payload

Todos os payloads de webhook seguem uma estrutura consistente com metadados de evento e dados.

Exemplo: evento qr.scanned

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

Exemplo: evento qr.created

{
  "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 de 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 X-Webhook-Signature cabeçalho contendo uma assinatura HMAC-SHA256 do corpo da solicitação.

Exemplo de Verificação em Node.js

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');
});

Exemplo de Verificação em Python

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', 200

Melhores Práticas

Responda rapidamente

Retorne uma resposta 2xx em até 5 segundos. Processar webhooks de forma assíncrona se o seu manuseio demorar mais.

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.

Monitore falhas

Configure monitoramento para falhas de entrega de webhook. Verifique os logs de webhook no painel para depuração.

Política de Retentativa

Se seu endpoint retornar um erro ou não responder, nós automaticamente tentamos a entrega novamente com retrocesso exponencial:

Tentativa	Atraso
1ª retentativa	1 minuto
2ª retentativa	5 minutos
3ª retentativa	30 minutos
4ª retentativa	2 horas
5ª retentativa (final)	24 horas

Nota: Após 5 tentativas falhadas, o webhook é marcado como falhado e paramos de tentar. Você receberá uma notificação por e-mail sobre a falha.

Próximos Passos

Pronto para começar? Explore mais recursos: