Apps API · Webhooks
Webhooks: 8 个接口
POST /api/v1/webhooks
Create webhook automation
权限(scope): automations:webhook:write · 调用方式: appToken · operationId: create-webhook
Required app scope: automations:webhook:write.
请求体
application/json · WebhookConfiguration
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
authorization_card_interaction_id |
string (uuid) | ||
authorization_confirmation_message_id |
string | ||
authorization_proposal_message_id |
string | ||
event_filter |
string | Optional bounded CEL boolean expression over payload; empty matches all | |
lead_member_id |
string (uuid) | 是 | |
owner_member_id |
string (uuid) | Human Owner UUID; omitted defaults to the human caller. Agent callers require an explicit human Owner | |
project_member_additions |
array of string | Members added to spec.project_id atomically with this write: only lead_member_id and/or owner_member_id, each once. The acting human (caller, or the confirming human for Agent writes) needs project write access. Must be empty for the Inbox | |
result_notification_policy |
string: every, failure_only, none |
Final result DM policy; omitted webhook creates default to failure_only. HTTP null is tolerated as omission | |
spec |
UpdateEventBindingSpec |
是 |
回包
200OK —application/json·WebhookCredentialResponseBodydefaultError —application/problem+json·D8Error
GET /api/v1/webhooks/{event_binding_id}
Read webhook configuration
权限(scope): automations:webhook:read · 调用方式: appToken · operationId: get-webhook
Required app scope: automations:webhook:read.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 | EventBinding UUID |
回包
200OK —application/json·DataResponseWebhookItemBodydefaultError —application/problem+json·D8Error
PUT /api/v1/webhooks/{event_binding_id}
Replace webhook configuration
权限(scope): automations:webhook:write · 调用方式: appToken · operationId: update-webhook
Required app scope: automations:webhook:write.
Changing a timer to a webhook creates a linked replacement and returns its secret URL once. Same-kind updates return an empty webhook_url.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 |
请求体
application/json · UpdateWebhookRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
authorization_card_interaction_id |
string (uuid) | ||
authorization_confirmation_message_id |
string | ||
authorization_proposal_message_id |
string | ||
event_filter |
string | Optional bounded CEL boolean expression over payload; empty matches all | |
expected_version |
integer (int64) | 是 | |
lead_member_id |
string (uuid) | 是 | |
owner_member_id |
string (uuid) | Human Owner UUID; omitted defaults to the human caller, not the previous owner. Agent callers require an explicit human Owner | |
project_member_additions |
array of string | Members added to spec.project_id atomically with this write: only lead_member_id and/or owner_member_id, each once. The acting human (caller, or the confirming human for Agent writes) needs project write access. Must be empty for the Inbox. A non-empty list also resumes an automation paused for LEAD_PROJECT_ACCESS_REQUIRED or OWNER_PROJECT_ACCESS_REQUIRED once every dependency validates. Where resume-on-save is enabled on the deployment, any save by the Owner (direct, or confirmed in chat) that passes every check resumes an automation paused for LEAD_PROJECT_ACCESS_REQUIRED, OWNER_PROJECT_ACCESS_REQUIRED, MEMBER_UNAVAILABLE, PRIVATE_LEAD_OWNER_CHANGED or PROJECT_UNAVAILABLE, with or without this list; never a manual pause, and an elapsed single run stays paused. Read enabled and pause_reason in the response | |
result_notification_policy |
string: every, failure_only, none |
Omitted preserves the current policy and migration notice; an explicit enum value clears the notice, even when unchanged. HTTP null is tolerated as omission | |
spec |
UpdateEventBindingSpec |
是 |
回包
200OK —application/json·WebhookCredentialResponseBodydefaultError —application/problem+json·D8Error
GET /api/v1/webhooks/{event_binding_id}/deliveries
Read a bounded window of webhook deliveries
权限(scope): automations:webhook:read · 调用方式: appToken · operationId: list-webhook-deliveries
Required app scope: automations:webhook:read.
Returns a bounded window without total or next-page metadata. Delivery status is not the created Issue's execution outcome.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 | EventBinding UUID |
limit |
query | integer (int32) | Maximum records in this bounded window; a full window does not guarantee more records exist | |
offset |
query | integer (int32) | Number of records to skip in the current history; separate requests do not share a snapshot |
回包
200OK —application/json·DataResponseListWebhookDeliveryItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/webhooks/{event_binding_id}/deliveries/{delivery_id}/retry
Retry a failed webhook delivery
权限(scope): automations:webhook:write · 调用方式: appToken · operationId: retry-webhook-delivery
Required app scope: automations:webhook:write.
Requeues the same failed delivery after the binding is resumed and dependencies are repaired. The server enforces authorization, version, retained payload and absence of an existing Issue.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 | |
delivery_id |
path | string (uuid) | 是 |
请求体
application/json · RetryWebhookDeliveryRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
expected_version |
integer (int64) | 是 |
回包
200OK —application/json·DataResponseWebhookDeliveryItemBodydefaultError —application/problem+json·D8Error
GET /api/v1/webhooks/{event_binding_id}/held-events
Read events held while the webhook automation was not running
权限(scope): automations:webhook:read · 调用方式: appToken · operationId: list-held-webhook-events
Required app scope: automations:webhook:read.
Events received while the automation was paused or the organization was suspended, waiting for the human Owner's replay decision: the replayable ones matching the current filter (oldest first, at most 200) with the expired and over-limit counts. Human Owner only; other members get 403 and a caller who cannot see the automation 404. 409 WORK_WEBHOOK_REPLAY_DISABLED while the feature is off.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 | Webhook EventBinding UUID |
回包
200OK —application/json·DataResponseHeldWebhookEventsBodydefaultError —application/problem+json·D8Error
POST /api/v1/webhooks/{event_binding_id}/held-events/decision
Decide whether to replay held webhook events
权限(scope): automations:webhook:write · 调用方式: appToken · operationId: decide-held-webhook-events
Required app scope: automations:webhook:write.
Applies the human Owner's replay decision to the events of the held-events read named by cursor: all, selected (delivery_ids) or none. Replayed events are queued with the current configuration and create their Issues in received order about 3 seconds apart; each event runs at most once. A repeated request_id returns the first result (reused). Human Owner only; other members get 403 and a caller who cannot see the automation 404. 409 WORK_WEBHOOK_PAUSED until the automation is resumed, WORK_ORG_SUSPENDED while the organization is suspended, WORK_WEBHOOK_REPLAY_DISABLED while the feature is off.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 | Webhook EventBinding UUID |
请求体
application/json · DecideHeldWebhookEventsRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cursor |
string | 是 | cursor of the held-events read this decision answers; an empty cursor (nothing was waiting) decides nothing |
delivery_ids |
array of string | Held delivery UUIDs to replay: at least one for mode selected, absent otherwise | |
mode |
string: all, selected, none |
是 | all replays every replayable event, selected replays delivery_ids, none replays nothing. Replayable events not replayed are recorded as declined; expired and over-limit ones as decided |
request_id |
string (uuid) | 是 | UUID chosen by the client per decision; repeating it returns the first result |
回包
200OK —application/json·DataResponseHeldWebhookEventsDecisionBodydefaultError —application/problem+json·D8Error
POST /api/v1/webhooks/{event_binding_id}/rotate
Rotate webhook URL credential
权限(scope): automations:webhook:write · 调用方式: appToken · operationId: rotate-webhook-token
Required app scope: automations:webhook:write.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 | EventBinding UUID |
请求体
application/json · ChangeEventBindingStateRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
expected_version |
integer (int64) | 是 | Current binding version for optimistic concurrency control |
回包
200OK —application/json·WebhookCredentialResponseBodydefaultError —application/problem+json·D8Error
