notpanel
服务价格常见问题福利活动API
notpanel

粉丝、点赞和观看,覆盖所有平台。

目录同时包含我们直接运营的服务和经过审核的合作伙伴容量。可用性、时间、补单和滴灌支持均按服务显示;路由和合作伙伴身份保持保密。

产品

  • 服务
  • 价格
  • 价格指数
  • 推荐计划

资源

  • API
  • 博客
  • 常见问题
  • 状态

公司

  • 关于
  • 为何选择 NotPanel
  • 联系我们

法律

  • 服务条款
  • 隐私政策
  • 退款政策

语言

  • English
  • Español
  • Português
  • Русский
  • Türkçe
  • العربية
  • हिन्दी
  • Bahasa Indonesia
  • Français
  • 中文

© 2026 NotPanel 版权所有。

support@notpanel.com
notpanel
API 文档
+
API 文档

简介

  • 概览
  • 快速开始
  • 身份验证
  • 速率限制
  • 错误

目录

  • 列出服务
  • 高级目录
  • 服务类型

订单

  • 下单
  • 订单状态
  • 退款报价
  • 补单
  • 取消

账户

  • 账户状态
  • 余额

Webhook

  • 管理 webhook

参考

  • 更新日志
  • SDK 与库

需要帮助?

support@notpanel.com →

注册 webhook

为公开 URL 订阅受支持的事件。每个端点都会获得独立的 HMAC-SHA256 密钥,该密钥仅在创建时显示一次。如果丢失,请移除端点后重新添加。

POSThttps://notpanel.com/api/v3action=webhook.add
需要 API key受速率限制(共享账户 + IP + action)请求体: application/x-www-form-urlencoded
每个 API key 最多 5 个 webhook。 请使用可从公网访问的 HTTPS URL。不安全、私有、回环或其他非公开目标会被拒绝。

参数

名称类型描述
key必需string你的 API key。
action必需string必须是字面字符串 “webhook.add”。
url必需string (URL)将接收 POST 请求的公开 HTTPS 端点。必须能从公网访问。
eventsstring (CSV)以逗号分隔的下方六个受支持事件的子集。省略时订阅全部六个。

请求示例

将 YOUR_API_KEY 替换为在你仪表盘 API 页面下生成的 key。

curl -X POST https://notpanel.com/api/v3 \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "key=YOUR_API_KEY&action=webhook.add&url=https://your-server.example.com/notpanel-webhook&events=order.completed,order.refunded"
const res = await fetch("https://notpanel.com/api/v3", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    key: "YOUR_API_KEY",
    action: "webhook.add",
    url: "https://your-server.example.com/notpanel-webhook",
    events: "order.completed,order.refunded",
  }),
});

const data = await res.json();
console.log(data);
import requests

res = requests.post(
  "https://notpanel.com/api/v3",
  data={
    "key": "YOUR_API_KEY",
    "action": "webhook.add",
    "url": "https://your-server.example.com/notpanel-webhook",
    "events": "order.completed,order.refunded",
},
)
print(res.json())
<?php
$body = http_build_query([
    'key' => 'YOUR_API_KEY',
    'action' => 'webhook.add',
    'url' => 'https://your-server.example.com/notpanel-webhook',
    'events' => 'order.completed,order.refunded',
]);

$response = file_get_contents('https://notpanel.com/api/v3', false, stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/x-www-form-urlencoded\r\n",
        'content' => $body,
        'ignore_errors' => true,
    ],
]));

print_r(json_decode($response, true));

响应示例

{
  "webhook_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "url": "https://your-server.example.com/notpanel-webhook",
  "secret": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "events": [
    "order.completed",
    "order.refunded"
  ]
}

常见错误

状态响应体原因
400{"error":"Maximum 5 webhook endpoints per API key"}现有端点已用尽上限。请先使用 action=webhook.remove 删除一个未使用的端点。
400{"error":"Webhook URL must be a publicly reachable HTTPS URL"}URL 不是有效的 HTTPS 地址、无法解析,或解析到了私有/回环 IP。
400{"error":"Webhook event is invalid","error_code":"INVALID_WEBHOOK_EVENT"}事件名称不在允许列表中。请重新检查拼写——名称采用 “order.<status>” 形式。

可用事件

  • order.completed
  • order.partial
  • order.processing
  • order.in_progress
  • order.refunded
  • order.refill_completed

列出 webhook

action=webhook.list 返回在调用 key 下注册的每个端点,包括其投递健康状况(status、failureCount、lastDeliveredAt)。

key=YOUR_API_KEY&action=webhook.list
[
  {
    "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "url": "https://your-server.example.com/notpanel-webhook",
    "events": ["order.completed", "order.refunded"],
    "status": "active",
    "failureCount": 0,
    "lastDeliveredAt": "2026-04-30T15:42:11.000Z",
    "createdAt": "2026-04-15T09:01:00.000Z"
  }
]

移除 webhook

使用 action=webhook.remove 并传入端点 UUID,可移除端点并吊销其签名密钥。正在进行的投递仍可能到达;不会再为其排队新事件。

key=YOUR_API_KEY&action=webhook.remove&id=3f2504e0-4f89-41d3-9a0c-0305e82c3301

{
  "success": true
}

投递载荷

每次投递都是带有 Content-Type: application/json 的 POST。请求体顶层包含 events、timestamp 和 deliveryId 字段。当前公开批处理默认最多聚合 5 秒,并包含最多 50 个事件对象;每个对象除 event、timestamp 和 data 外,还含稳定的逻辑 id。队列或故障可能增加延迟,因此这不是 5 秒投递承诺。请求头包括:

  • X-Webhook-Signature —— sha256=&lt;hex&gt;,基于 &lt;timestamp&gt;.&lt;原始 JSON 请求体字节&gt; 计算。
  • X-Webhook-Timestamp —— 此次投递的 Unix 时间戳(秒)。
  • X-Webhook-Delivery-Id —— 批次投递 UUID;重试同一批次时会复用。没有投递级事件请求头;请从请求体读取每个事件。
{
  "events": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "event": "order.completed",
      "timestamp": 1777534931,
      "data": {
        "order": 7001,
        "orderId": 7001,
        "serviceId": 1,
        "status": "Completed",
        "status_key": "completed",
        "charge": "0.50",
        "startCount": 1234,
        "remains": 0
      }
    }
  ],
  "timestamp": 1777534931,
  "deliveryId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

验证签名

读取 X-Webhook-Timestamp 和实际收到的原始 JSON 请求体字节。使用端点密钥对 &lt;timestamp&gt;.&lt;请求体字节&gt; 计算 HMAC-SHA256,格式化为 sha256=&lt;hex&gt;,再以恒定时间与 X-Webhook-Signature 比较。重试会保留事件 ID 和 deliveryId,但会获得新的 timestamp、body 和 signature。

作为你自己的防重放策略,可拒绝签名正确但时间戳与服务器时钟相差超过 5 分钟的投递。

投递行为与重试

  • 带重试的尽力而为投递。2xx 响应即完成投递。每次尝试在 30 秒后超时。失败可能从 5 秒后开始重试,并采用指数退避,最长为 5 分钟,但并不提供持久的至少一次投递保证。
  • 暂停阈值。连续失败 10 次后端点会暂停。没有 enable 或 update action;请移除它,再使用 action=webhook.add 注册替代端点并保存新显示的密钥。
  • 不保证顺序。处理程序应保持幂等、处理批次中的每个事件,使用事件 id 去重逻辑状态变化,或使用 deliveryId 去重重试批次,并通过 action=status 核对重要状态。