Manage subscriptions with the API

Manage subscriptions with the API when an integration should set up its own webhooks, for example when a customer connects your product to their Drum account.

Before you begin

You need an API token whose user has:

• The manage_webhooks permission
• api_read, and api_create, api_update or api_delete for the calls you make

See Create an API token. The examples use $DRUM_TOKEN for the token.

1. Create the subscription

curl -X POST https://app.getdrum.com/api/v1/webhook_subscriptions \
  -H "Authorization: Bearer $DRUM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_subscription": {
      "name": "Accounting sync",
      "url": "https://example.com/drum/webhooks",
      "subscribed_events": ["invoice.created", "invoice.updated"]
    }
  }'

The response is 201 with the subscription and its secret:

{
  "id": 41,
  "name": "Accounting sync",
  "url": "https://example.com/drum/webhooks",
  "status": "active",
  "subscribed_events": ["invoice.created", "invoice.updated"],
  "delivery_attempts_count": 0,
  "consecutive_failures": 0,
  "last_triggered_at": null,
  "disabled_at": null,
  "disabled_reason": null,
  "created_at": "2026-10-13T01:02:03.000000Z",
  "updated_at": "2026-10-13T01:02:03.000000Z",
  "created_by": {"id": 57, "name": "Integration User"},
  "secret": "Xk3...",
  "secret_warning": "This is the only time the secret will be displayed. Store it securely."
}

2. Store the id and the secret

Store id and secret together. The API does not return the secret again, only a secret_hint with its first and last four characters. A person with manage_webhooks can still copy it from the subscription’s page in Drum.

If the save fails, the response is 422 with the reasons:

{"errors": ["Url must be a valid HTTPS URL"]}

3. Find an existing subscription

Before you create a subscription, check whether your integration made one already, so you do not send every event twice:

curl https://app.getdrum.com/api/v1/webhook_subscriptions \
  -H "Authorization: Bearer $DRUM_TOKEN"

The list is newest first, 20 to a page. Add ?page=2 for the next page. Match on url.

4. Change the events or the URL

Send only the fields you are changing:

curl -X PATCH https://app.getdrum.com/api/v1/webhook_subscriptions/41 \
  -H "Authorization: Bearer $DRUM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"webhook_subscription": {"subscribed_events": ["invoice.created", "invoice.updated", "cost.created"]}}'

subscribed_events replaces the whole list, so send every event you want to keep.

5. Pause, resume or delete it

When a customer disconnects your integration, delete its subscription, so Drum stops sending events.

Errors

Every endpoint and field is in Subscription endpoints.