Webhooks

Receive real-time notifications when tasks complete or fail

Overview

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.

Available Events

task.completedTriggered when a task completes successfully

task.failedTriggered when a task fails

GET/api/v1/webhooks

List all your webhook configurations

Response

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

Request Body

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

Body Fields

Parameter	Type	Required	Description
url	string	Required	Your webhook endpoint URL
events	string[]	Required	Events to subscribe to
secret_key	string	Optional	Secret for signature verification

Response

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

Response

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

Webhook Payload

When an event occurs, we'll send a POST request to your webhook URL with the following payload:

Headers

Header	Description
X-Webhook-Timestamp	Unix timestamp of the request
X-Webhook-Signature	HMAC-SHA256 signature for verification

Example Payload

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

Signature Verification

Verify webhook authenticity using 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;
}