웹훅

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

개요

Webhooks allow you to receive HTTP callbacks when your image or video generation tasks complete. Instead of polling for results, you can set up a webhook endpoint to receive automatic notifications.

사용 가능한 이벤트

job.completedTriggered when a task completes successfully
job.failedTriggered when a task fails

API 엔드포인트

GET/api/v1/webhooks

List all your webhook configurations

응답 예시:

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

POST/api/v1/webhooks

Create a new webhook endpoint

요청 예시:

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

매개변수:

Parameter	타입	필수	설명
url	string	필수	Your webhook endpoint URL
events	string[]	필수	Events to subscribe to
secret_key	string	선택 사항	Secret for signature verification

응답 예시:

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

DELETE/api/v1/webhooks/{id}

Delete a webhook endpoint

응답 예시:

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

웹훅 페이로드

웹훅 알림이 귀하의 엔드포인트로 전송되는 형식

헤더	설명
X-Nano-Timestamp	Unix timestamp of the request
X-Nano-Signature	HMAC-SHA256 signature for verification

예시 페이로드:

{
  "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"
}

서명 검증

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