---
title: "Update a webhook subscription"
method: PATCH
path: "/webhooks/{id}"
---

# Update a webhook subscription

`PATCH /webhooks/{id}`

## Request

- Base URL: `https://craaft.io/api/v1`
- URL: `https://craaft.io/api/v1/webhooks/{id}`
- Auth: HTTP bearer

Board admins on Pro boards only (authz via subscription lookup).
Partial update - send only the fields to change. A downgraded (Free)
board gets 402 here; DELETE stays open so it can still clean up.

## Request body

- object
  - `url` string, uri
  - `description` string
  - `format` 'craaft' | 'slack' | 'discord'
  - `events` string[]
  - `active` boolean

## Response `200`

Updated

- WebhookSubscription
  - `id` string, uuid, required: Subscription id (the handle for update/delete)
  - `endpointId` string, uuid, required: Endpoint id at the workspace level
  - `url` string, uri, required: The target URL for deliveries
  - `secret` string, required: HMAC signing secret for 'craaft' deliveries (X-Craaft-Signature). Returned on every read to board admins. Slack/Discord deliveries are unsigned and ignore it.
  - `description` string, required: Optional label
  - `format` 'craaft' | 'slack' | 'discord', required: Delivery format (craaft=signed JSON envelope; slack/discord=message POST)
  - `events` string[], required: Event filter (empty=all events; non-empty=only listed events)
  - `active` boolean, required
  - `createdAt` string, date-time, required
  - `recentDeliveries` WebhookDelivery[]: Last few delivery attempts (most recent first), capped at 10
    - `event` string, required: The broadcast event name (e.g. 'card.created')
    - `status` 'delivered' | 'failed', required: Delivery outcome
    - `statusCode` integer, required: HTTP status code from the webhook URL
    - `attempts` integer, required: Number of delivery attempts
    - `error` string, required: Error message when status is failed; empty string on success (never null)
    - `createdAt` string, date-time, required

## Other responses

- `400`: Malformed body or invalid format/events
- `401`: Missing or invalid token
- `402`: Free plan - integrations need Pro
- `403`: Not a board admin
- `404`: Resource doesn't exist or caller isn't a member of its workspace

---

[API](https://skmtc.dev/craaft/apis/craaft-api.md) · [All operations](https://skmtc.dev/craaft/apis/craaft-api/llms.txt) · [OpenAPI document](https://skmtc.dev/craaft/apis/craaft-api/revisions/3a1e9d30d7dc?raw)