Webhooks - Documentation API - iloveQR

Documentation API

Webhooks

Recevez des notifications en temps réel lorsque des événements se produisent dans votre organisation. Les Webhooks vous permettent de créer des intégrations réactives qui répondent immédiatement aux scans de QR codes et à d'autres événements.

Temps réel

Soyez instantanément informé lorsque des événements se produisent, sans besoin de polling

Sécurisé

Les signatures HMAC vérifient que les webhooks proviennent d'iloveQR

Fiable

Réessais automatiques avec un backoff exponentiel pour les livraisons échouées

Configuration des Webhooks

Configurez les webhooks via le tableau de bord ou l'API pour commencer à recevoir des événements.

Créer un point de terminaison webhook

Configurez un point de terminaison HTTPS sur votre serveur pour recevoir les charges utiles des webhooks.

Enregistrer le webhook

Ajoutez l'URL de votre point de terminaison et sélectionnez les événements auxquels vous souhaitez vous abonner.

Vérifier les signatures

Implémentez la vérification des signatures pour garantir que les charges utiles sont authentiques.

Enregistrer le 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"
  }'

Événements Webhook

Abonnez-vous aux événements dont vous avez besoin. Chaque type d'événement a une structure de charge utile spécifique.

Événements QR Code

qr.createdUn nouveau QR code a été créé

qr.updatedUn QR code a été mis à jour

qr.deletedUn QR code a été supprimé

qr.scannedUn QR code a été scanné

qr.archivedUn QR code a été archivé

qr.restoredUn QR code a été restauré depuis l'archive

Événements d'abonnement

subscription.createdUn nouvel abonnement a été créé

subscription.updatedUn abonnement a été mis à jour

subscription.cancelledUn abonnement a été annulé

subscription.payment_succeededUn paiement a été réussi

subscription.payment_failedUn paiement a échoué

Événements d'équipe

member.joinedUn membre a rejoint l'organisation

member.leftUn membre a quitté l'organisation

member.role_changedLe rôle d'un membre a été changé

Charge utile du Webhook

Toutes les charges utiles des webhooks suivent une structure cohérente avec des métadonnées d'événements et des données.

Exemple : événement 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
    }
  }
}

Exemple : événement 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"
    }
  }
}

Vérification des Webhooks

Vérifiez toujours les signatures des webhooks pour garantir que la charge utile provient d'iloveQR et n'a pas été altérée en transit.

En-tête de signature

Chaque requête webhook inclut un X-Webhook-Signature en-tête contenant une signature HMAC-SHA256 du corps de la requête.

Exemple de vérification 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');
});

Exemple de vérification 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

Meilleures pratiques

Répondez rapidement

Retournez une réponse 2xx dans les 5 secondes. Traitez les webhooks de manière asynchrone si votre traitement prend plus de temps.

Gérer les doublons

Stockez l'ID de l'événement et vérifiez les doublons. Les webhooks peuvent être livrés plus d'une fois dans de rares cas.

Utilisez HTTPS

Utilisez toujours des points de terminaison HTTPS. Nous ne livrons pas de webhooks à des URL HTTP.

Surveillez les échecs

Mettez en place une surveillance des échecs de livraison des webhooks. Vérifiez les journaux des webhooks dans le tableau de bord pour le débogage.

Politique de réessai

Si votre point de terminaison renvoie une erreur ou ne répond pas, nous réessayons automatiquement la livraison avec un backoff exponentiel :

Tentative	Délai
1er réessai	1 minute
2ème réessai	5 minutes
3ème essai	30 minutes
4ème essai	2 heures
5ème essai (final)	24 heures

Note : Après 5 tentatives échouées, le webhook est marqué comme échoué et nous arrêtons les tentatives. Vous recevrez une notification par e-mail concernant l'échec.

Prochaines étapes

Prêt à commencer ? Explorez plus de ressources :