Documentação da API
Webhooks

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.

1

Criar um endpoint de webhook

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

2

Registrar o webhook

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

3

Verificar assinaturas

Implemente a verificação de assinatura para garantir que os payloads sejam autênticos.

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 payload específica.

Eventos de QR Code

qr.createdUm novo código QR foi criado
qr.updatedUm código QR foi atualizado
qr.deletedUm código QR foi excluído
qr.scannedUm código QR foi escaneado
qr.archivedUm código QR foi arquivado
qr.restoredUm código QR 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 da Equipe

member.joinedUm membro entrou na organização
member.leftUm membro deixou a organização
member.role_changedO papel de um membro foi alterado

Carga Útil do Webhook

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

Exemplo: qr.scanned Evento
{
  "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: qr.created Evento
{
  "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.

Exemplo de Verificação 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 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:

TentativaAtraso
1ª tentativa1 minuto
2ª tentativa5 minutos
3ª tentativa30 minutos
4ª tentativa2 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: