Webhooks API 参考：端点与示例

OpenAPI YAML OpenAPI JSON 问题 YAML API 概览

此分组有 9 个操作，由 api/openapi.yaml 生成。可按路径、操作或认证筛选。每个端点都会列出其输入；展开后可查看请求模板和响应代码。模板需要您自己的值和符合架构的请求体。

用你的值替换大写占位符。对于JSON请求，请保存符合request.json模式的请求体。Cookie示例使用经过身份验证会话的本地Cookie存储。

Webhooks：签名事件传递

GET/api/webhooks¶

列出 webhook

以 Webhook 的数据结构按从旧到新的顺序列出项目的 Webhook 通知（最多 50 个）；GET /api/notifications 会列出所有渠道的通知。此处绝不会返回签名密钥。需要项目权限；仅有报告权限的凭据会被拒绝并返回 403 forbidden，因为响应包含接收方 URL。

身份验证: projectBearer 或 dashboardSession
请求主体: 无
操作 ID: listWebhooks

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks'

响应

状态	含义	正文和头部
200	项目 webhook。	WebhookList（application/json）
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

POST/api/webhooks¶

创建 webhook

创建一个 webhook，接收项目自身的持久事件，作为签名的 HTTPS POST。url 必须是公共互联网主机上的 https：IP 字面量或该名称的所有当前 DNS 解析均为公共（拒绝私有、回环、链路本地、CGNAT、IPv6 非 2000::/3、文档及其他保留范围，返回 webhook_url_rejected）。

端口必须是 443（默认）或 8443，否则为 webhook_url_rejected。主机在每次传递前解析并再次检查，连接精确拨号至检查的地址，因此后续 DNS 变更无法重定向传递。event_types 列出精确事件类型（screen.online）或以 .* 结尾的前缀（screen.*）。

每个组织最多有 50 个通知，涵盖所有渠道（webhook_limit_reached）。签名密钥由服务器生成，仅在本次响应和 rotate-secret 中返回；请妥善保存。以相同的 Idempotency-Key 原样重试，24 小时内会返回同一响应（包括密钥）。

投递从 notification.created 之后的第一个事件开始。

身份验证: projectBearer
请求主体: WebhookWrite
操作 ID: createWebhook

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
url（必填，字符串）	公共互联网主机上的https URL，端口443（默认）或8443。不含用户信息或片段。maxLength：2048 格式：“uri”
event_types（必填，WebhookEventTypes）	精确的事件类型（如 screen.online），或以 .* 结尾的前缀（如 screen.*，即所有以 screen. 开头的类型）。notification.test 永远不会通过订阅分发；它只会由 POST /api/webhooks/{id}/test 发送。
启用（可选，布尔值）	默认：true
描述（可选，字符串）	maxLength：200

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/webhooks'

响应

状态	含义	正文和头部
201	已创建。密钥仅在此处及密钥轮换时显示。	WebhookWithSecret（application/json）；头部：Cache-Control
400	invalid_request 或 webhook_url_rejected。	问题 (application/problem+json)
409	webhook_limit_reached、idempotency_mismatch，或在项目不属于任何组织时返回 resource_conflict。	问题 (application/problem+json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

GET/api/webhooks/{id}¶

获取 webhook

需要项目权限；仅报告凭证因响应包含接收器 URL 而被拒绝 403 禁止。

身份验证: projectBearer 或 dashboardSession
请求主体: 无
操作 ID: getWebhook

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID'

响应

状态	含义	正文和头部
200	一个 webhook。	Webhook（application/json）；头部：ETag
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

PATCH/api/webhooks/{id}¶

更新 Webhook

更改 url、event_types、enabled 和 description（空描述将清除）。新 url 会像创建时一样检查。

在禁用的 webhook 上设置 enabled 为 true 会清除失败状态，并从记录更改的事件开始投递；禁用期间的事件不重放，禁用前待投递的仍失败并标记 webhook_disabled。设置 enabled 为 false 会使待投递失败并标记 webhook_disabled。

追加 notification.updated。If-Match 用于保护修订号。

身份验证: projectBearer
请求主体: WebhookPatch
操作 ID: updateWebhook

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id	路径	必填
If-Match	header	可选	可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
url（可选，字符串）	maxLength：2048 格式：“uri”
event_types（可选，WebhookEventTypes）	精确的事件类型（如 screen.online），或以 .* 结尾的前缀（如 screen.*，即所有以 screen. 开头的类型）。notification.test 永远不会通过订阅分发；它只会由 POST /api/webhooks/{id}/test 发送。
启用（可选，布尔值）
描述（可选，字符串）	空字符串会清除描述。maxLength：200

请求模板和响应

shell · 请求模板

curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/webhooks/RESOURCE_ID'

响应

状态	含义	正文和头部
200	已更新 Webhook。	Webhook（application/json）；头部：ETag
400	invalid_request 或 webhook_url_rejected。	问题 (application/problem+json)
412	revision_conflict — If-Match 已过期；错误的 current_revision 包含当前版本。	问题 (application/problem+json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

删除/api/webhooks/{id}¶

删除 Webhook

删除该 Webhook 并追加 notification.deleted。其待处理的投递会以 webhook_deleted 标记为失败；其投递日志不再可访问，并随事件保留期一同过期。

身份验证: projectBearer 或 dashboardSession
请求主体: 无
操作 ID: deleteWebhook

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id	路径	必填
If-Match	header	可选	可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求模板和响应

shell · 请求模板

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID'

响应

状态	含义	正文和头部
204	已删除。	无正文；头部：Cache-Control
412	revision_conflict — If-Match 已过期；错误的 current_revision 包含当前版本。	问题 (application/problem+json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

POST/api/webhooks/{id}/rotate-secret¶

轮换 Webhook 密钥

替换签名密钥并返回新密钥；旧密钥会立即停止用于签名：此操作提交之后签名的每一次尝试都使用新密钥，而每个 Webhook 最多有一次已在传输中的尝试仍可能以旧密钥签名送达，因此请短时间内同时接受新旧两个密钥。追加 notification.updated，details.changed 为 [secret]。

携带相同 Idempotency-Key 的精确重试在 24 小时内返回相同的新密钥。

身份验证: projectBearer
请求主体: 无
操作 ID: rotateWebhookSecret

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id	路径	必填
If-Match	header	可选	可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/webhooks/RESOURCE_ID/rotate-secret'

响应

状态	含义	正文和头部
200	带有新密钥的 webhook。	WebhookWithSecret（application/json）；头部：Cache-Control
412	revision_conflict — If-Match 已过期；错误的 current_revision 包含当前版本。	问题 (application/problem+json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

POST/api/webhooks/{id}/test¶

测试 Webhook

追加一个 notification.test 项目事件，并仅为此 Webhook 排入一次该事件的投递（其他 Webhook 不会收到 notification.test）。它对已禁用的 Webhook 同样有效，仅尝试一次且不重试，与任何投递一样计量，并且绝不改变该 Webhook 的失败状态。请轮询投递日志查看其结果。

身份验证: projectBearer
请求主体: 无
操作 ID: testWebhook

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/webhooks/RESOURCE_ID/test'

响应

状态	含义	正文和头部
202	排队的测试投放。	WebhookDelivery（application/json）；头部：RateLimit-Policy，RateLimit
429	稳定的 rate_limited 问题。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。	问题 (application/problem+json)；头部：Retry-After，RateLimit-Policy，RateLimit
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

GET/api/webhooks/{id}/deliveries¶

列出 webhook 交付记录

webhook 的交付日志，最新事件优先。每个（webhook，事件）一行；重试会更新该行，GET .../deliveries/{delivery_id}/attempts 列出其最近尝试。行保留时间与事件相同（计划的事件保留，至少 24 小时重试窗口）。传回 next_cursor 以获取下一页。

身份验证: projectBearer 或 dashboardSession
请求主体: 无
操作 ID: listWebhookDeliveries

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id	路径	必填
before	查询	可选	上一交付页的 next_cursor。
限制	查询	可选

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID/deliveries'

响应

状态	含义	正文和头部
200	一页投递记录。	WebhookDeliveryList（application/json）
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

GET/api/webhooks/{id}/deliveries/{delivery_id}/attempts¶

列出 webhook 交付尝试

一次投递的尝试，最新的优先，最多 20 条，随投递行保存且长期保留。每条包含尝试编号、完成时间、接收方 HTTP 状态（无响应时为 null）、错误类别（成功时为 null）及持续时间。响应体和头部从不保存。投递记录在尝试记录之前的列出为空。

非本 webhook 的投递，或属于其他项目的 webhook，返回 not_found。

身份验证: projectBearer 或 dashboardSession
请求主体: 无
操作 ID: listWebhookDeliveryAttempts

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id	路径	必填
delivery_id	路径	必填	某个 webhook 投递的 ID。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID/deliveries/DELIVERY_ID/attempts'

响应

状态	含义	正文和头部
200	交付的保留尝试。	WebhookDeliveryAttemptList（application/json）
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)