Webhooks

Webhook 是您服务器上的一个地址，当发生某些事情时 Posty5 会调用它。您的系统无需向 Posty5 查询新的访问，而会在几秒内收到通知，并附带可验证的 JSON 事件。

创建端点

在 Posty5 控制台中，打开账户设置并选择 Webhooks。
添加一个端点，输入其 HTTPS 地址并选择它接收的事件。
选择全部或部分链接和二维码、是否计入机器人访问，以及事件是逐个到达还是批量到达。
保存，然后复制签名密钥。它只显示这一次。
使用发送测试来检查您的服务器能否接收并验证 webhook.test 事件。

地址必须使用 HTTPS 且可从互联网访问。私有和本地网络地址会被拒绝，且不会跟随重定向。您最多可以拥有 10 个端点。

事件

Event
`short_link.visited`	有人打开了您的某个短链接，包括通过该链接的二维码图片打开。
`short_link.visits_milestone`	短链接达到了您设置的某个访问次数（最多 10 个值）。
`qr_code.scanned`	有人扫描了您的某个动态二维码。
`qr_code.scans_milestone`	二维码达到了您设置的某个扫描次数。
`webhook.test`	仅在您使用发送测试时发送。

事件的样子

每个事件都是一个 JSON POST，包含 id、类型、API 版本、创建时间及其数据，即链接或二维码以及访问信息。

{
  "id": "evt_6700f1c2a9e4b51d2c3f0a11",
  "type": "short_link.visited",
  "apiVersion": "2026-10-01",
  "createdAt": "2026-10-04T12:00:00.000Z",
  "data": {
    "target": {
      "type": "shortLink",
      "id": "66f0c2a9e4b51d2c3f0a1122",
      "code": "aB3xY9",
      "url": "https://pst5.com/_aB3xY9",
      "name": "Spring sale",
      "destinationUrl": "https://shop.example/sale",
      "tag": "spring",
      "refId": null
    },
    "visit": {
      "at": "2026-10-04T11:59:59.120Z",
      "channel": "qr",
      "country": "EG",
      "deviceType": "mobile",
      "os": "Android",
      "browser": "Chrome",
      "referrerHost": null,
      "language": "ar",
      "isBot": false,
      "outcome": "redirect"
    }
  }
}

里程碑事件携带 data.milestone，其中包含指标、达到的值和达到时间，不包含访问信息。

使用批量投递时，一个类型为 batch 的 POST 会在 data.events 中携带最多 500 个事件。

永远不会发送的内容

事件从不包含访问者的 IP 地址、完整的用户代理、完整的来源地址、访问者标识符或您的账户 ID。除非您选择包含，否则机器人访问会被排除。

验证签名

Posty5 按照 Standard Webhooks 规范，使用您端点的密钥为每次投递签名，签名位于三个标头中。请拒绝任何签名不匹配或时间戳超过 5 分钟的请求。

webhook-id
webhook-timestamp
webhook-signature

在 Node.js 中，使用 @posty5/webhooks 包。

import { verifyWebhookSignature } from "@posty5/webhooks";

// rawBody is the request body exactly as received, before JSON parsing.
const event = verifyWebhookSignature({
  payload: rawBody,
  headers: request.headers,
  secret: process.env.POSTY5_WEBHOOK_SECRET,
});

在 .NET 中，使用 Posty5.Webhooks 包。

using Posty5.Webhooks;

var webhookEvent = WebhookSignature.Verify(rawBody, headers, secret);

在其他任何语言中，任何 Standard Webhooks 库都可以用您的密钥验证 Posty5 事件。

重试和失败

请在 10 秒内以任意 2xx 状态响应。其他任何响应都算作失败。
失败的投递会在 30 秒、2 分钟、10 分钟、1 小时、6 小时和 24 小时后重试，之后放弃。
每次重试都携带相同的 webhook-id，因此您的服务器可以忽略已处理过的事件。
端点在至少 24 小时内连续 20 次投递失败后会被关闭，如果它响应 410 Gone 则立即关闭。您会收到通知，并可以在控制台中重新开启它。
端点的投递记录会显示每次尝试及其状态和您服务器的响应，并允许您再次发送某次投递。

轮换密钥

如果密钥可能已泄露，请从端点的菜单中轮换它。在 24 小时内，投递会携带两个签名，每个密钥一个，以便您更新服务器而不会错过事件。

无需代码，在 n8n 中使用

Posty5 Trigger 节点会为您创建并验证端点。 n8n Posty5 Trigger