用途:当用户希望在自己的 URL 上实时接收 X(Twitter)事件时使用。事件来自监控(账号、话题标签、提及)以及抽奖(draws)。
主要能力:通过 API 创建、列出、启停、删除 Webhook,并可轮换密钥、发送测试载荷。创建时返回 webhook_id 与 secret,secret 用于校验传入载荷的 HMAC-SHA256 签名。
接口与用法:Base URL 为 https://xquik.com/api/v1,认证使用 x-api-key: xq_... 请求头。POST /webhooks 创建(计费为 Subscription),GET /webhooks 列出(Read tier),PATCH /webhooks/{id} 启停或轮换密钥(Read tier),DELETE /webhooks/{id} 删除(Read tier),POST /webhooks/{id}/test 发送测试载荷(Read tier)。创建示例:{"url": "https://example.com/xquik-hook", "events": ["monitor.event", "draw.completed"], "secret": "<可选,省略则自动生成>"},返回 { webhook_id, secret }。
签名校验:每次投递包含 X-Xquik-Signature: sha256=<hex> 头,用户服务器需计算 hmac_sha256(secret, raw_body) 并做常量时间比较。
典型流程:确认目标 URL 为 HTTPS 且可达;询问用户订阅哪些事件;仅在用户批准后创建(该 URL 将收到真实数据);调用 POST /webhooks/{id}/test 发送样例载荷并确认已到达且校验通过;定期通过 PATCH /webhooks/{id} 轮换密钥。
限制与安全:Webhook URL 必须为 HTTPS;必须校验 X-Xquik-Signature,未校验不得信任载荷;不得代用户注册第三方 URL,端点须由用户自己拥有。相关:监控创建见 monitor-accounts,完整 API 见 x-twitter-scraper。