NB

Webhooks

任务完成或失败时，实时接收通知

概述

Webhooks 允许您在图像或视频生成任务完成时接收 HTTP 回调。您无需轮询结果，只需设置一个 webhook 端点即可自动接收通知。

可用事件

task.completed任务成功完成时触发
task.failed任务失败时触发
GET/api/v1/webhooks
列出您所有的Webhook配置

回复

{
  "success": true,
  "data": [
    {
      "id": 1,
      "url": "https://your-server.com/webhook",
      "events": ["job.completed", "job.failed"],
      "status": "active"
    }
  ]
}
POST/api/v1/webhooks
创建新的Webhook端点

请求正文

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

正文字段

参数类型必需描述
urlstring必需您的Webhook端点URL
eventsstring[]必需订阅事件
secret_keystring可选签名验证密钥

回复

{
  "success": true,
  "data": {
    "id": 1,
    "url": "https://your-server.com/webhook",
    "events": ["job.completed", "job.failed"],
    "status": "active"
  }
}
DELETE/api/v1/webhooks/{id}
删除 Webhook 端点

回复

{
  "success": true,
  "data": { "id": 1 }
}
Webhook 负载
当事件发生时，我们会向你的 webhook URL 发送一个 POST 请求，并附带以下数据负载：

页眉

页首描述
X-Webhook-Timestamp请求的 Unix 时间戳
X-Webhook-SignatureHMAC-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验证Webhook真实性
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;
}
Nano Banana Pro API