組織内でイベントが発生したときにリアルタイム通知を受け取ります。Webhookを使用すると、QRコードのスキャンやその他のイベントに即座に反応するリアクティブな統合を構築できます。
イベントが発生したときに即座に通知を受け取ります。ポーリングは不要です。
HMAC署名により、WebhookがiloveQRからのものであることが確認されます。
失敗した配信のための指数バックオフによる自動再試行
ダッシュボードまたはAPIを通じてWebhookを構成して、イベントの受信を開始します。
Webhookペイロードを受信するためにサーバー上にHTTPSエンドポイントを設定します。
エンドポイントURLを追加し、購読するイベントを選択してください。
ペイロードが正当であることを確認するために署名検証を実装してください。
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"
}'必要なイベントに購読してください。各イベントタイプには特定のペイロード構造があります。
qr.created新しいQRコードが作成されましたqr.updatedQRコードが更新されましたqr.deletedQRコードが削除されましたqr.scannedQRコードがスキャンされましたqr.archivedQRコードがアーカイブされましたqr.restoredQRコードがアーカイブから復元されましたsubscription.created新しいサブスクリプションが作成されましたsubscription.updatedサブスクリプションが更新されましたsubscription.cancelledサブスクリプションがキャンセルされましたsubscription.payment_succeeded支払いが成功しましたsubscription.payment_failed支払いに失敗しましたmember.joinedメンバーが組織に参加しましたmember.leftメンバーが組織を離れましたmember.role_changedメンバーの役割が変更されましたすべてのWebhookペイロードは、イベントメタデータとデータを含む一貫した構造に従います。
{
"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
}
}
}{
"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の署名を検証して、ペイロードがiloveQRから来たものであり、転送中に改ざんされていないことを確認してください。
各Webhookリクエストには、リクエストボディのHMAC-SHA256署名を含むX-Webhook-Signatureヘッダーが含まれています。
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');
});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', 2005秒以内に2xxレスポンスを返してください。処理に時間がかかる場合は、Webhookを非同期で処理してください。
イベントIDを保存し、重複をチェックしてください。Webhookは稀に複数回配信されることがあります。
常にHTTPSエンドポイントを使用してください。HTTP URLにはWebhookを配信しません。
Webhook配信の失敗を監視する設定をしてください。デバッグのためにダッシュボードのWebhookログを確認してください。
エンドポイントがエラーを返すか応答しない場合、指数バックオフで自動的に配信を再試行します:
| 試行 | 遅延 |
|---|---|
| 1回目の再試行 | 1分 |
| 2回目の再試行 | 5分 |
| 3回目の再試行 | 30分 |
| 4回目の再試行 | 2時間 |
| 5回目の再試行（最終） | 24時間 |
注意: 5回の失敗した試行の後、Webhookは失敗としてマークされ、再試行を停止します。失敗についてのメール通知が届きます。
始める準備はできましたか？さらにリソースを探ってください: