Apps API · Webhooks
Webhooks: 8 endpoints
POST /api/v1/webhooks
Create webhook automation
Scope: automations:webhook:write · Called with: appToken · operationId: create-webhook
Required app scope: automations:webhook:write.
Request body
application/json · WebhookConfiguration
| Field | Type | Required | Description |
|---|---|---|---|
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) | yes | |
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 |
yes |
Responses
200OK —application/json·WebhookCredentialResponseBodydefaultError —application/problem+json·D8Error
GET /api/v1/webhooks/{event_binding_id}
Read webhook configuration
Scope: automations:webhook:read · Called with: appToken · operationId: get-webhook
Required app scope: automations:webhook:read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes | EventBinding UUID |
Responses
200OK —application/json·DataResponseWebhookItemBodydefaultError —application/problem+json·D8Error
PUT /api/v1/webhooks/{event_binding_id}
Replace webhook configuration
Scope: automations:webhook:write · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes |
Request body
application/json · UpdateWebhookRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
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) | yes | |
lead_member_id |
string (uuid) | yes | |
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 |
yes |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes | 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 |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes | |
delivery_id |
path | string (uuid) | yes |
Request body
application/json · RetryWebhookDeliveryRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
expected_version |
integer (int64) | yes |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes | Webhook EventBinding UUID |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes | Webhook EventBinding UUID |
Request body
application/json · DecideHeldWebhookEventsRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
cursor |
string | yes | 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 |
yes | 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) | yes | UUID chosen by the client per decision; repeating it returns the first result |
Responses
200OK —application/json·DataResponseHeldWebhookEventsDecisionBodydefaultError —application/problem+json·D8Error
POST /api/v1/webhooks/{event_binding_id}/rotate
Rotate webhook URL credential
Scope: automations:webhook:write · Called with: appToken · operationId: rotate-webhook-token
Required app scope: automations:webhook:write.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes | EventBinding UUID |
Request body
application/json · ChangeEventBindingStateRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
expected_version |
integer (int64) | yes | Current binding version for optimistic concurrency control |
Responses
200OK —application/json·WebhookCredentialResponseBodydefaultError —application/problem+json·D8Error
