Organization API: Billing & Payouts: Webhooks
The 7 Organization API operations for webhooks.
Part of Billing & Payouts.
Operations
Section titled Operations| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/orgs/{org_slug}/webhooks |
List webhooks |
| POST | /api/v1/orgs/{org_slug}/webhooks |
Create webhook |
| GET | /api/v1/orgs/{org_slug}/webhooks/{webhook_id} |
One webhook, as GET /webhooks lists it |
| PATCH | /api/v1/orgs/{org_slug}/webhooks/{webhook_id} |
A new address is checked as on create (422) |
| DELETE | /api/v1/orgs/{org_slug}/webhooks/{webhook_id} |
Delete webhook |
| GET | /api/v1/orgs/{org_slug}/webhooks/{webhook_id}/deliveries |
List webhook deliveries |
| POST | /api/v1/orgs/{org_slug}/webhooks/{webhook_id}/rotate-secret |
A fresh signingsecret, in this answer only |
List webhooks
Section titled List webhooksGET /api/v1/orgs/{org_slug}/webhooks
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
org_slug |
path | string | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
A 200 response is a list; each item has these fields:
| Field | Type |
|---|---|
[].id |
integer |
[].org_id |
integer |
[].url |
string |
[].events |
array of any |
[].is_active |
boolean |
[].failure_count |
integer |
[].last_triggered_at |
string (date-time) or null |
[].created_at |
string (date-time) or null |
Create webhook
Section titled Create webhookPOST /api/v1/orgs/{org_slug}/webhooks
A webhook for an https address outside the platform, or on the
organization's own deployment on App Deployment (422 otherwise).
The answer carries signing_secret; no later answer does, except the
one that rotates it.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
org_slug |
path | string | yes |
Request body
Section titled Request bodyapplication/json (required)
| Field | Type | Required |
|---|---|---|
url |
string | yes |
events |
array of string | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
201 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Fields of a 201 response:
| Field | Type |
|---|---|
id |
integer |
org_id |
integer |
url |
string |
events |
array of any |
is_active |
boolean |
failure_count |
integer |
last_triggered_at |
string (date-time) or null |
created_at |
string (date-time) or null |
signing_secret |
string |
One webhook, as GET /webhooks lists it
Section titled One webhook, as GET /webhooks lists itGET /api/v1/orgs/{org_slug}/webhooks/{webhook_id}
One webhook, as GET /webhooks lists it. Owners and admins; 404 for
a webhook of another organization.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
webhook_id |
path | integer | yes |
org_slug |
path | string | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Fields of a 200 response:
| Field | Type |
|---|---|
id |
integer |
org_id |
integer |
url |
string |
events |
array of any |
is_active |
boolean |
failure_count |
integer |
last_triggered_at |
string (date-time) or null |
created_at |
string (date-time) or null |
A new address is checked as on create (422)
Section titled A new address is checked as on create (422)PATCH /api/v1/orgs/{org_slug}/webhooks/{webhook_id}
A new address is checked as on create (422).
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
webhook_id |
path | integer | yes |
org_slug |
path | string | yes |
Request body
Section titled Request bodyapplication/json (required)
| Field | Type | Required |
|---|---|---|
url |
string or null | no |
events |
array of string or null | no |
is_active |
boolean or null | no |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Fields of a 200 response:
| Field | Type |
|---|---|
id |
integer |
org_id |
integer |
url |
string |
events |
array of any |
is_active |
boolean |
failure_count |
integer |
last_triggered_at |
string (date-time) or null |
created_at |
string (date-time) or null |
Delete webhook
Section titled Delete webhookDELETE /api/v1/orgs/{org_slug}/webhooks/{webhook_id}
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
webhook_id |
path | integer | yes |
org_slug |
path | string | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
List webhook deliveries
Section titled List webhook deliveriesGET /api/v1/orgs/{org_slug}/webhooks/{webhook_id}/deliveries
What the webhook was sent and how its receiver answered, newest first, without the payloads or the answers' bodies.
with_total=true answers {items, total, limit, offset, counts},
counts per status whatever the status filter. 404 for another
organization's webhook.
Parameters
Section titled Parameters| Name | In | Type | Required | Description |
|---|---|---|---|---|
webhook_id |
path | integer | yes | |
org_slug |
path | string | yes | |
status_filter |
query | string or null | no | One of pending, sending, delivered, failed, cancelled. |
limit |
query | integer | no | Default: 50. |
offset |
query | integer | no | Default: 0. |
with_total |
query | boolean | no | Default: False. |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
A fresh signingsecret, in this answer only
Section titled A fresh signingsecret, in this answer onlyPOST /api/v1/orgs/{org_slug}/webhooks/{webhook_id}/rotate-secret
A fresh signing_secret, in this answer only. The old one stops at
once: every delivery from now on, retries of earlier events included, is
signed with the new one.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
webhook_id |
path | integer | yes |
org_slug |
path | string | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Fields of a 200 response:
| Field | Type |
|---|---|
id |
integer |
org_id |
integer |
url |
string |
events |
array of any |
is_active |
boolean |
failure_count |
integer |
last_triggered_at |
string (date-time) or null |
created_at |
string (date-time) or null |
signing_secret |
string |