웹훅 - API 문서 - iloveQR

API 문서

웹훅

조직에서 이벤트가 발생할 때 실시간 알림을 받습니다. 웹훅을 사용하면 QR 코드 스캔 및 기타 이벤트에 즉시 반응하는 반응형 통합을 구축할 수 있습니다.

실시간

이벤트가 발생할 때 즉시 알림을 받으며, 폴링이 필요하지 않습니다.

안전한

HMAC 서명이 웹훅이 iloveQR에서 온 것임을 확인합니다.

신뢰할 수 있는

실패한 전송에 대해 지수 백오프를 사용한 자동 재시도

웹훅 설정

대시보드 또는 API를 통해 웹훅을 구성하여 이벤트 수신을 시작합니다.

웹훅 엔드포인트 생성

서버에 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 코드 이벤트

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구성원의 역할이 변경되었습니다

웹훅 페이로드

모든 웹훅 페이로드는 이벤트 메타데이터와 데이터를 포함한 일관된 구조를 따릅니다.

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

웹훅 검증

웹훅 서명을 항상 확인하여 페이로드가 iloveQR에서 왔고 전송 중에 변조되지 않았는지 확인합니다.

서명 헤더

각 웹훅 요청에는 요청 본문의 HMAC-SHA256 서명을 포함하는 X-Webhook-Signature 헤더가 포함됩니다.

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 응답을 반환합니다. 처리 시간이 더 걸리는 경우 웹훅을 비동기적으로 처리합니다.

중복 처리

이벤트 ID를 저장하고 중복 여부를 확인합니다. 웹훅은 드물게 여러 번 전달될 수 있습니다.

HTTPS 사용

항상 HTTPS 엔드포인트를 사용하세요. HTTP URL에는 웹훅을 전달하지 않습니다.

모니터링 실패

웹훅 전송 실패에 대한 모니터링을 설정하세요. 디버깅을 위해 대시보드에서 웹훅 로그를 확인하세요.

재시도 정책

엔드포인트가 오류를 반환하거나 응답하지 않으면, 우리는 자동으로 지수 백오프 방식으로 전송을 재시도합니다:

시도	지연
1차 재시도	1분
2차 재시도	5분
3차 재시도	30분
4차 재시도	2시간
5차 재시도 (최종)	24시간

참고: 5번의 실패한 시도 후, 웹훅은 실패로 표시되며 재시도를 중단합니다. 실패에 대한 이메일 알림을 받게 됩니다.

다음 단계

시작할 준비가 되셨나요? 더 많은 리소스를 탐색하세요:

웹훅

실시간

이벤트가 발생할 때 즉시 알림을 받으며, 폴링이 필요하지 않습니다.

안전한

HMAC 서명이 웹훅이 iloveQR에서 온 것임을 확인합니다.

신뢰할 수 있는

실패한 전송에 대해 지수 백오프를 사용한 자동 재시도

웹훅 설정

대시보드 또는 API를 통해 웹훅을 구성하여 이벤트 수신을 시작합니다.

웹훅 엔드포인트 생성

서버에 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 코드 이벤트

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구성원의 역할이 변경되었습니다

웹훅 페이로드

모든 웹훅 페이로드는 이벤트 메타데이터와 데이터를 포함한 일관된 구조를 따릅니다.

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

웹훅 검증

웹훅 서명을 항상 확인하여 페이로드가 iloveQR에서 왔고 전송 중에 변조되지 않았는지 확인합니다.

서명 헤더

각 웹훅 요청에는 요청 본문의 HMAC-SHA256 서명을 포함하는 X-Webhook-Signature 헤더가 포함됩니다.

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 응답을 반환합니다. 처리 시간이 더 걸리는 경우 웹훅을 비동기적으로 처리합니다.

중복 처리

이벤트 ID를 저장하고 중복 여부를 확인합니다. 웹훅은 드물게 여러 번 전달될 수 있습니다.

HTTPS 사용

항상 HTTPS 엔드포인트를 사용하세요. HTTP URL에는 웹훅을 전달하지 않습니다.

모니터링 실패

웹훅 전송 실패에 대한 모니터링을 설정하세요. 디버깅을 위해 대시보드에서 웹훅 로그를 확인하세요.

재시도 정책

엔드포인트가 오류를 반환하거나 응답하지 않으면, 우리는 자동으로 지수 백오프 방식으로 전송을 재시도합니다:

시도	지연
1차 재시도	1분
2차 재시도	5분
3차 재시도	30분
4차 재시도	2시간
5차 재시도 (최종)	24시간

참고: 5번의 실패한 시도 후, 웹훅은 실패로 표시되며 재시도를 중단합니다. 실패에 대한 이메일 알림을 받게 됩니다.

다음 단계

시작할 준비가 되셨나요? 더 많은 리소스를 탐색하세요: