Help

Subscription endpoints

These endpoints manage webhook subscriptions in the token’s account. They follow the API conventions, with the differences below.

   
Base URL https://app.getdrum.com/api/v1/
Permissions manage_webhooks, plus the API permission for the method (api_read, api_create, api_update, api_delete)
Rate limit 100 requests a minute per IP address, across all webhook endpoints, on top of the API’s own limits
Pagination page and items, as for other list endpoints. Newest first

Subscriptions

Method and path Does
GET /api/v1/webhook_subscriptions Lists subscriptions
GET /api/v1/webhook_subscriptions/:id Reads one
POST /api/v1/webhook_subscriptions Creates one. Returns 201
PATCH /api/v1/webhook_subscriptions/:id Changes name, url or subscribed_events
PATCH /api/v1/webhook_subscriptions/:id/pause Pauses it
PATCH /api/v1/webhook_subscriptions/:id/resume Makes a paused or disabled subscription active and resets its failure count
DELETE /api/v1/webhook_subscriptions/:id Deletes it and stops its deliveries. Returns 204. Afterwards the subscription and its deliveries answer 404, though Drum keeps the delivery history until it expires

pause, resume and PATCH return the subscription.

Create or change a subscription

Send the fields under webhook_subscription:

POST /api/v1/webhook_subscriptions
{
  "webhook_subscription": {
    "name": "Accounting sync",
    "url": "https://example.com/drum/webhooks",
    "subscribed_events": ["project.created", "invoice.updated"]
  }
}
Field Rules
name Required, up to 255 characters
url Required, up to 2,048 characters. Must be https. localhost, 127.0.0.1, ::1 and .local hosts are refused. Other private addresses are refused when Drum sends, which disables the subscription
subscribed_events Required. At least one of the events. On PATCH it replaces the whole list

Create returns the subscription, its secret and a secret_warning message. Reading, changing, pausing and resuming one subscription return a secret_hint (the first and last four characters) instead. The list returns neither. The secret is also shown on the subscription’s page in Drum.

A save that fails returns 422 with {"errors": [...]}, for example {"errors": ["Subscribed events contains invalid events: project.deleted"]}.

The subscription object

Field Meaning
id, name, url, subscribed_events As set
status active, paused or disabled
delivery_attempts_count Deliveries made so far
consecutive_failures Failed deliveries in a row
last_triggered_at The last successful delivery
disabled_at, disabled_reason Set when Drum disabled the subscription
created_by {id, name} of the member who created it
created_at, updated_at Timestamps
secret Only in the response to create
secret_hint Only when reading or changing one subscription

Deliveries

Method and path Does
GET /api/v1/webhook_subscriptions/:id/webhook_deliveries Lists the subscription’s deliveries
GET /api/v1/webhook_subscriptions/:id/webhook_deliveries/:delivery_id Reads one delivery, with the request and response
POST /api/v1/webhook_subscriptions/:id/webhook_deliveries/:delivery_id/retry Sends a delivery again, as a new delivery

Reading needs api_read. Retrying is a POST, so it needs api_create.

The delivery object

Field Meaning
id, event_type, resource_type, resource_id What was sent. resource_type is the payload’s data.type
status pending (not sent yet, or waiting for its next attempt), success or failed
attempt_count Attempts made, up to 5
response_status, error_message The last attempt’s result
delivered_at When it succeeded
created_at When the event was recorded
request_payload On a single delivery only. The body Drum sent
request_headers On a single delivery only. Always {}. The headers are listed in Requests and signatures
response_body, response_headers On a single delivery only. Secrets in them are redacted

Retry

Retry copies the delivery, with the same body, and sends the copy:

202 Accepted
{"message": "Delivery retry scheduled", "delivery_id": 991}

delivery_id is the new delivery. A delivery that succeeded cannot be retried, and returns 422 with {"error": "Cannot retry a successful delivery"}. The copy is sent only while the subscription is active.

Errors

Status Body Cause
403 {"error": "Forbidden"} The token’s user does not have manage_webhooks, or the API permission for the method
404 {"error": "Webhook subscription not found"} or {"error": "Webhook delivery not found"} Not in the token’s account, or deleted
422 {"errors": [...]} The subscription’s fields are not valid
429   Over the rate limit