Webhooks - API 文檔 - iloveQR

API 文件

Webhooks

當事件在您的組織中發生時，接收實時通知。Webhooks 允許您構建反應式集成，立即響應 QR 碼掃描和其他事件。

實時

當事件發生時立即獲得通知，無需輪詢

安全

HMAC 簽名驗證 Webhooks 來自 iloveQR

可靠

對於失敗的交付，自動重試並使用指數退避

設置 Webhooks

通過儀表板或 API 配置 Webhooks 以開始接收事件。

創建 Webhook 端點

在您的伺服器上設置 HTTPS 端點以接收 Webhook 負載。

註冊 Webhook

添加您的端點 URL 並選擇要訂閱的事件。

驗證簽名

實施簽名驗證以確保負載的真實性。

註冊 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"
  }'

Webhook 事件

訂閱您需要的事件。每種事件類型都有特定的負載結構。

QR 碼事件

qr.created已創建新的 QR 碼

qr.updated已更新 QR 碼

qr.deleted已刪除 QR 碼

qr.scanned已掃描 QR 碼

qr.archived已歸檔 QR 碼

qr.restored已從歸檔中恢復 QR 碼

訂閱事件

subscription.created已創建新的訂閱

subscription.updated已更新訂閱

subscription.cancelled已取消訂閱

subscription.payment_succeeded付款成功

subscription.payment_failed付款失敗

團隊事件

member.joined成員加入組織

member.left成員離開組織

member.role_changed成員的角色已更改

Webhook 負載

所有 webhook 負載遵循一致的結構，包含事件元數據和數據。

範例：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
    }
  }
}

範例：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"
    }
  }
}

驗證 Webhook

始終驗證 webhook 簽名，以確保負載來自 iloveQR 並且在傳輸過程中未被篡改。

簽名標頭

每個 webhook 請求都包含一個 X-Webhook-Signature 標頭，該標頭包含請求主體的 HMAC-SHA256 簽名。

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

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

最佳實踐

快速回應

在 5 秒內返回 2xx 響應。如果處理時間較長，請異步處理 webhook。

處理重複項

儲存事件 ID 並檢查重複項。在少數情況下，webhook 可能會多次傳送。

使用 HTTPS

始終使用 HTTPS 端點。我們不會將 webhook 傳送到 HTTP URL。

監控失敗

設置 webhook 傳送失敗的監控。在儀表板中檢查 webhook 日誌以進行調試。

重試政策

如果您的端點返回錯誤或未響應，我們會自動以指數退避的方式重試傳送：

嘗試	延遲
第一次重試	1 分鐘
第二次重試	5 分鐘
第三次重試	30 分鐘
第四次重試	2 小時
第五次重試（最終）	24 小時

注意： 在 5 次失敗嘗試後，該 webhook 將被標記為失敗，我們將停止重試。您將收到有關失敗的電子郵件通知。

後續步驟

準備好開始了嗎？探索更多資源：

Webhooks

當事件在您的組織中發生時，接收實時通知。Webhooks 允許您構建反應式集成，立即響應 QR 碼掃描和其他事件。

實時

當事件發生時立即獲得通知，無需輪詢

安全

HMAC 簽名驗證 Webhooks 來自 iloveQR

可靠

對於失敗的交付，自動重試並使用指數退避

設置 Webhooks

通過儀表板或 API 配置 Webhooks 以開始接收事件。

創建 Webhook 端點

在您的伺服器上設置 HTTPS 端點以接收 Webhook 負載。

註冊 Webhook

添加您的端點 URL 並選擇要訂閱的事件。

驗證簽名

實施簽名驗證以確保負載的真實性。

註冊 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"
  }'

Webhook 事件

訂閱您需要的事件。每種事件類型都有特定的負載結構。

QR 碼事件

qr.created已創建新的 QR 碼

qr.updated已更新 QR 碼

qr.deleted已刪除 QR 碼

qr.scanned已掃描 QR 碼

qr.archived已歸檔 QR 碼

qr.restored已從歸檔中恢復 QR 碼

訂閱事件

subscription.created已創建新的訂閱

subscription.updated已更新訂閱

subscription.cancelled已取消訂閱

subscription.payment_succeeded付款成功

subscription.payment_failed付款失敗

團隊事件

member.joined成員加入組織

member.left成員離開組織

member.role_changed成員的角色已更改

Webhook 負載

所有 webhook 負載遵循一致的結構，包含事件元數據和數據。

範例：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
    }
  }
}

範例：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"
    }
  }
}

驗證 Webhook

始終驗證 webhook 簽名，以確保負載來自 iloveQR 並且在傳輸過程中未被篡改。

簽名標頭

每個 webhook 請求都包含一個 X-Webhook-Signature 標頭，該標頭包含請求主體的 HMAC-SHA256 簽名。

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

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

最佳實踐

快速回應

在 5 秒內返回 2xx 響應。如果處理時間較長，請異步處理 webhook。

處理重複項

儲存事件 ID 並檢查重複項。在少數情況下，webhook 可能會多次傳送。

使用 HTTPS

始終使用 HTTPS 端點。我們不會將 webhook 傳送到 HTTP URL。

監控失敗

設置 webhook 傳送失敗的監控。在儀表板中檢查 webhook 日誌以進行調試。

重試政策

如果您的端點返回錯誤或未響應，我們會自動以指數退避的方式重試傳送：

嘗試	延遲
第一次重試	1 分鐘
第二次重試	5 分鐘
第三次重試	30 分鐘
第四次重試	2 小時
第五次重試（最終）	24 小時

注意： 在 5 次失敗嘗試後，該 webhook 將被標記為失敗，我們將停止重試。您將收到有關失敗的電子郵件通知。

後續步驟

準備好開始了嗎？探索更多資源：