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

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

API Endpoints

GET/api/v1/webhooks

List all your webhook configurations

Response Example:

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

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

Parameters:

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 Example:

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

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

Webhook Payload

Format of webhook notifications sent to your endpoint

Header	Description
X-Nano-Timestamp	Unix timestamp of the request
X-Nano-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

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