Webhooki - Dokumentacja API - iloveQR

Dokumentacja API

Webhooki

Otrzymuj powiadomienia w czasie rzeczywistym, gdy wydarzenia mają miejsce w Twojej organizacji. Webhooki pozwalają na budowanie reaktywnych integracji, które natychmiast reagują na skanowanie kodów QR i inne wydarzenia.

Czas rzeczywisty

Bądź natychmiast powiadamiany, gdy wydarzenia mają miejsce, bez potrzeby odpytywania

Bezpieczne

Podpisy HMAC weryfikują, że webhooki pochodzą z iloveQR

Niezawodne

Automatyczne ponowne próby z wykładniczym opóźnieniem dla nieudanych dostaw

Konfiguracja Webhooków

Skonfiguruj webhooki za pośrednictwem pulpitu nawigacyjnego lub API, aby zacząć otrzymywać wydarzenia.

Utwórz punkt końcowy webhooka

Skonfiguruj punkt końcowy HTTPS na swoim serwerze, aby odbierać ładunki webhooków.

Zarejestruj webhook

Dodaj swój adres URL punktu końcowego i wybierz, do jakich wydarzeń chcesz się subskrybować.

Weryfikuj podpisy

Wdróż weryfikację podpisów, aby upewnić się, że ładunki są autentyczne.

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

Wydarzenia Webhooków

Subskrybuj wydarzenia, których potrzebujesz. Każdy typ wydarzenia ma określoną strukturę ładunku.

Wydarzenia kodów QR

qr.createdUtworzono nowy kod QR

qr.updatedKod QR został zaktualizowany

qr.deletedKod QR został usunięty

qr.scannedKod QR został zeskanowany

qr.archivedKod QR został zarchiwizowany

qr.restoredKod QR został przywrócony z archiwum

Wydarzenia subskrypcyjne

subscription.createdUtworzono nową subskrypcję

subscription.updatedSubskrypcja została zaktualizowana

subscription.cancelledSubskrypcja została anulowana

subscription.payment_succeededPłatność została zrealizowana

subscription.payment_failedPłatność nie powiodła się

Wydarzenia zespołu

member.joinedCzłonek dołączył do organizacji

member.leftCzłonek opuścił organizację

member.role_changedRola członka została zmieniona

Ładunek Webhooka

Wszystkie ładunki webhooków mają spójną strukturę z metadanymi wydarzenia i danymi.

Przykład: zdarzenie 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
    }
  }
}

Przykład: zdarzenie 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"
    }
  }
}

Weryfikacja Webhooków

Zawsze weryfikuj podpisy webhooków, aby upewnić się, że ładunek pochodzi z iloveQR i nie został zmieniony w trakcie przesyłania.

Nagłówek podpisu

Każde żądanie webhooka zawiera nagłówek X-Webhook-Signature zawierający podpis HMAC-SHA256 ciała żądania.

Przykład weryfikacji 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');
});

Przykład weryfikacji Pythona

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

Najlepsze praktyki

Reaguj szybko

Zwróć odpowiedź 2xx w ciągu 5 sekund. Przetwarzaj webhooki asynchronicznie, jeśli Twoje przetwarzanie zajmuje więcej czasu.

Zarządzaj duplikatami

Przechowuj identyfikator zdarzenia i sprawdzaj duplikaty. Webhooki mogą być dostarczane więcej niż raz w rzadkich przypadkach.

Użyj HTTPS

Zawsze używaj punktów końcowych HTTPS. Nie dostarczamy webhooków do adresów URL HTTP.

Monitoruj błędy

Skonfiguruj monitorowanie błędów dostarczania webhooków. Sprawdź logi webhooków w panelu do debugowania.

Polityka ponawiania

Jeśli Twój punkt końcowy zwraca błąd lub nie odpowiada, automatycznie ponawiamy dostarczanie z wykładniczym opóźnieniem:

Próba	Opóźnienie
1. ponowienie	1 minuta
2. ponowienie	5 minut
3. ponowienie	30 minut
4. ponowienie	2 godziny
5. ponowienie (ostateczne)	24 godziny

Uwaga: Po 5 nieudanych próbach, webhook jest oznaczany jako nieudany i przestajemy ponawiać. Otrzymasz powiadomienie e-mail o niepowodzeniu.

Następne kroki

Gotowy do rozpoczęcia? Zbadaj więcej zasobów: