Webhook - Documentazione API - iloveQR

Documentazione API

Webhook

Ricevi notifiche in tempo reale quando si verificano eventi nella tua organizzazione. I webhook ti consentono di costruire integrazioni reattive che rispondono immediatamente alle scansioni di codici QR e ad altri eventi.

In tempo reale

Ricevi notifiche istantanee quando si verificano eventi, senza polling richiesto

Sicuro

Le firme HMAC verificano che i webhook provengano da iloveQR

Affidabile

Ritenti automatici con backoff esponenziale per le consegne non riuscite

Impostazione dei Webhook

Configura i webhook tramite la dashboard o l'API per iniziare a ricevere eventi.

Crea un endpoint webhook

Imposta un endpoint HTTPS sul tuo server per ricevere i payload dei webhook.

Registra il webhook

Aggiungi l'URL del tuo endpoint e seleziona a quali eventi iscriverti.

Verifica le firme

Implementa la verifica delle firme per garantire che i payload siano autentici.

Registra 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"
  }'

Eventi Webhook

Iscriviti agli eventi di cui hai bisogno. Ogni tipo di evento ha una struttura di payload specifica.

Eventi QR Code

qr.createdÈ stato creato un nuovo QR code

qr.updatedUn QR code è stato aggiornato

qr.deletedUn QR code è stato eliminato

qr.scannedUn QR code è stato scansionato

qr.archivedUn QR code è stato archiviato

qr.restoredUn QR code è stato ripristinato dall'archivio

Eventi di Abbonamento

subscription.createdÈ stato creato un nuovo abbonamento

subscription.updatedUn abbonamento è stato aggiornato

subscription.cancelledUn abbonamento è stato annullato

subscription.payment_succeededUn pagamento è andato a buon fine

subscription.payment_failedUn pagamento è fallito

Eventi di Team

member.joinedUn membro si è unito all'organizzazione

member.leftUn membro ha lasciato l'organizzazione

member.role_changedIl ruolo di un membro è stato cambiato

Payload Webhook

Tutti i payload dei webhook seguono una struttura coerente con i metadati dell'evento e i dati.

Esempio: 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
    }
  }
}

Esempio: 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"
    }
  }
}

Verifica dei Webhook

Verifica sempre le firme dei webhook per garantire che il payload provenga da iloveQR e non sia stato manomesso durante il transito.

Intestazione della Firma

Ogni richiesta webhook include un'intestazione X-Webhook-Signature contenente una firma HMAC-SHA256 del corpo della richiesta.

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

Esempio di Verifica 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

Migliori Pratiche

Rispondi rapidamente

Restituisci una risposta 2xx entro 5 secondi. Elabora i webhook in modo asincrono se la tua gestione richiede più tempo.

Gestisci i duplicati

Memorizza l'ID dell'evento e controlla i duplicati. I webhook possono essere consegnati più di una volta in rari casi.

Usa HTTPS

Usa sempre endpoint HTTPS. Non consegniamo webhook a URL HTTP.

Monitora i fallimenti

Imposta il monitoraggio per i fallimenti di consegna dei webhook. Controlla i log dei webhook nella dashboard per il debug.

Politica di Riprova

Se il tuo endpoint restituisce un errore o non risponde, riproviamo automaticamente la consegna con un backoff esponenziale:

Tentativo	Ritardo
1° riprova	1 minuto
2° riprova	5 minuti
3° riprova	30 minuti
4° riprova	2 ore
5° riprova (finale)	24 ore

Nota: Dopo 5 tentativi falliti, il webhook viene contrassegnato come fallito e smettiamo di riprovare. Riceverai una notifica via email riguardo al fallimento.

Prossimi Passi

Pronto per iniziare? Esplora ulteriori risorse: