Rob Zolkos
21981898d2
* Add JSON API for webhook deliveries * Extract sanitized_request method on Webhook::Delivery * Extract response_summary method on Webhook::Delivery
162 lines
4.0 KiB
Markdown
162 lines
4.0 KiB
Markdown
# Webhooks
|
|
|
|
Webhooks notify another application when something happens on a board. Only account admins can list, view, create, update, delete, or reactivate webhooks.
|
|
|
|
## `GET /:account_slug/boards/:board_id/webhooks`
|
|
|
|
Returns a paginated list of webhooks for a board.
|
|
|
|
__Response:__
|
|
|
|
```json
|
|
[
|
|
{
|
|
"id": "03f5v9zkft4hj9qq0lsn9ohcm",
|
|
"name": "Production API",
|
|
"payload_url": "https://api.example.com/webhooks",
|
|
"active": true,
|
|
"signing_secret": "p94Bx2HjempCdYB4DTyZkY1b",
|
|
"subscribed_actions": ["card_published", "card_assigned", "card_closed"],
|
|
"created_at": "2025-12-05T19:36:35.534Z",
|
|
"url": "http://fizzy.localhost:3006/897362094/boards/03f5v9zkft4hj9qq0lsn9ohcy/webhooks/03f5v9zkft4hj9qq0lsn9ohcm",
|
|
"board": {
|
|
"id": "03f5v9zkft4hj9qq0lsn9ohcy",
|
|
"name": "Fizzy",
|
|
"all_access": true,
|
|
"created_at": "2025-12-05T19:36:35.534Z",
|
|
"url": "http://fizzy.localhost:3006/897362094/boards/03f5v9zkft4hj9qq0lsn9ohcy",
|
|
"creator": {
|
|
"id": "03f5v9zjw7pz8717a4no1h8a7",
|
|
"name": "David Heinemeier Hansson",
|
|
"role": "owner",
|
|
"active": true,
|
|
"email_address": "david@example.com",
|
|
"created_at": "2025-12-05T19:36:35.401Z",
|
|
"url": "http://fizzy.localhost:3006/897362094/users/03f5v9zjw7pz8717a4no1h8a7"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
```
|
|
|
|
## `GET /:account_slug/boards/:board_id/webhooks/:id`
|
|
|
|
Returns a single webhook.
|
|
|
|
__Response:__
|
|
|
|
Returns the same webhook shape shown above.
|
|
|
|
## `POST /:account_slug/boards/:board_id/webhooks`
|
|
|
|
Creates a webhook.
|
|
|
|
__Request:__
|
|
|
|
```json
|
|
{
|
|
"webhook": {
|
|
"name": "Production API",
|
|
"url": "https://api.example.com/webhooks",
|
|
"subscribed_actions": ["card_published", "card_assigned", "card_closed"]
|
|
}
|
|
}
|
|
```
|
|
|
|
`subscribed_actions` accepts any of:
|
|
`card_assigned`, `card_closed`, `card_postponed`, `card_auto_postponed`, `card_board_changed`, `card_published`, `card_reopened`, `card_sent_back_to_triage`, `card_triaged`, `card_unassigned`, `comment_created`
|
|
|
|
__Response:__
|
|
|
|
```
|
|
HTTP/1.1 201 Created
|
|
Location: http://fizzy.localhost:3006/897362094/boards/03f5v9zkft4hj9qq0lsn9ohcy/webhooks/03f5v9zkft4hj9qq0lsn9ohcm.json
|
|
```
|
|
|
|
Returns the created webhook in the response body.
|
|
|
|
## `PATCH /:account_slug/boards/:board_id/webhooks/:id`
|
|
|
|
Updates a webhook.
|
|
|
|
__Request:__
|
|
|
|
```json
|
|
{
|
|
"webhook": {
|
|
"name": "Production API",
|
|
"subscribed_actions": ["card_closed"]
|
|
}
|
|
}
|
|
```
|
|
|
|
The `url` is immutable after creation and is ignored on update.
|
|
|
|
__Response:__
|
|
|
|
Returns the updated webhook.
|
|
|
|
## `DELETE /:account_slug/boards/:board_id/webhooks/:id`
|
|
|
|
Deletes a webhook.
|
|
|
|
__Response:__
|
|
|
|
Returns `204 No Content` on success.
|
|
|
|
## `POST /:account_slug/boards/:board_id/webhooks/:id/activation`
|
|
|
|
Reactivates a deactivated webhook.
|
|
|
|
__Response:__
|
|
|
|
```
|
|
HTTP/1.1 201 Created
|
|
```
|
|
|
|
Returns the reactivated webhook in the response body.
|
|
|
|
## `GET /:account_slug/boards/:board_id/webhooks/:webhook_id/deliveries`
|
|
|
|
Returns a paginated list of deliveries for a webhook. Only account admins can access delivery history.
|
|
|
|
__Response:__
|
|
|
|
```json
|
|
[
|
|
{
|
|
"id": "03f5v9zkft4hj9qq0lsn9ohdn",
|
|
"state": "completed",
|
|
"created_at": "2025-12-05T19:36:35.534Z",
|
|
"updated_at": "2025-12-05T19:36:36.102Z",
|
|
"request": {
|
|
"headers": {
|
|
"User-Agent": "fizzy/1.0.0 Webhook",
|
|
"Content-Type": "application/json",
|
|
"X-Webhook-Timestamp": "2025-12-05T19:36:35.401Z"
|
|
}
|
|
},
|
|
"response": {
|
|
"code": 200,
|
|
"error": null
|
|
},
|
|
"event": {
|
|
"id": "03f5v9zkft4hj9qq0lsn9ohde",
|
|
"action": "card_closed",
|
|
"created_at": "2025-12-05T19:36:35.401Z",
|
|
"creator": {
|
|
"id": "03f5v9zjw7pz8717a4no1h8a7",
|
|
"name": "David Heinemeier Hansson"
|
|
},
|
|
"eventable": {
|
|
"type": "Card",
|
|
"id": "03f5v9zkft4hj9qq0lsn9ohdb",
|
|
"url": "http://fizzy.localhost:3006/897362094/cards/1"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
```
|
|
|
|
`request` and `response` can be `null` for deliveries that have not started yet or are still in progress. The delivery request headers omit the `X-Webhook-Signature` header.
|