웹훅

작업이 완료되거나 실패할 때 실시간 알림을 받으세요

개요

웹훅을 사용하면 이미지나 동영상 생성 작업이 완료될 때 HTTP 콜백을 받을 수 있습니다. 결과를 수동으로 확인하는 대신 웹훅 엔드포인트를 설정하여 자동 알림을 받을 수 있습니다.

사용 가능한 이벤트

task.completed작업이 성공적으로 완료되었을 때 트리거됩니다

task.failed작업이 실패했을 때 트리거됩니다

GET/api/v1/webhooks

모든 웹훅 설정 목록 조회하기

응답

{
  "success": true,
  "data": [
    {
      "id": 1,
      "url": "https://your-server.com/webhook",
      "events": ["job.completed", "job.failed"],
      "status": "active"
    }
  ]
}

POST/api/v1/webhooks

새로운 웹훅 엔드포인트 생성하기

요청 본문

{
  "url": "https://your-server.com/webhook",
  "events": ["job.completed", "job.failed"],
  "secret_key": "your-secret-key"
}

바디 필드

Parameter	타입	필수	설명
url	string	필수	웹훅 엔드포인트 URL
events	string[]	필수	구독할 이벤트
secret_key	string	선택 사항	서명 검증을 위한 비밀 키

응답

{
  "success": true,
  "data": {
    "id": 1,
    "url": "https://your-server.com/webhook",
    "events": ["job.completed", "job.failed"],
    "status": "active"
  }
}

DELETE/api/v1/webhooks/{id}

웹훅 엔드포인트 삭제하기

응답

{
  "success": true,
  "data": { "id": 1 }
}

웹훅 페이로드

이벤트가 발생하면, 다음과 같은 페이로드를 담아 귀하의 웹훅 URL로 POST 요청을 보냅니다:

헤더

헤더	설명
X-Webhook-Timestamp	요청의 유닉스 타임스탬프
X-Webhook-Signature	확인을 위한 HMAC-SHA256 서명

예시 페이로드

{
  "event": "job.completed",
  "task_id": "task_xxx",
  "task_type": "image",
  "status": "completed",
  "data": {
    "url": "https://cdn.example.com/image.png",
    "credits_charged": 6
  },
  "timestamp": "2024-12-23T10:00:00Z"
}

서명 검증

HMAC-SHA256을 사용하여 웹훅의 진위성을 확인합니다

const crypto = require('crypto');

function verifySignature(payload, signature, secret, timestamp) {
  const message = `${timestamp}.${JSON.stringify(payload)}`;
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  return `v1=${expectedSig}` === signature;
}