Update a webhook

Overview

Change a subscription's URL, label, event filter, or settings. Send only what changes.

Use this when you move your endpoint or want different events.

You'll need the subscription id.

The subscription is updated. The secret is unchanged; to replace it, use Rotate the signing secret.

Prerequisites

A Partner bearer token. See Authentication.
The subscription's id, from List your webhooks.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

POST /api/v1/partner/webhooks/{webhookSubscriptionId}/update

Authentication

Partner token

Only partner users can call it; other tokens get 403.
Only your own partner's subscriptions: any other id, including another partner's, gets 404.

Rate limit

This endpoint has no rate limit.

Request parameters

Parameter	In	Type	Required	Description
`webhookSubscriptionId`	path	integer	Yes	The subscription's id, from List your webhooks.

Request body

Field	Type	Required	Description
`label`	string	No	Your name for the subscription. Up to 255 characters; can't be empty when sent.
`webhook_url`	string	No	Your endpoint's HTTPS URL. Up to 2048 characters.
`is_active`	boolean	No	`false` pauses deliveries; `true` turns them back on.
`delivery_kind`	string	No	`immediate` or `batch`. You can have one of each, so switching to the kind you already have elsewhere gets `422`.
`batch_interval_hours`	integer	No	Hours between batches: `1`, `2`, `4`, `6` or `12`. Required when you switch `delivery_kind` to `batch`.
`events`	array of strings	No	Replaces the event filter (immediate only), by `value` from the events catalogue; only `immediate` events can be picked. `[]` or `null`: all immediate events. Ignored on a batch subscription (stored as `null`).
`payload_mode`	string	No	Immediate only: `full` or `minimal`. A batch subscription is always `full`.

Request payload

{
  "label": "Updated webhook label",
  "webhook_url": "https://partner.example.com/hooks/sau-v2",
  "is_active": true,
  "payload_mode": "minimal"
}

Response body

The payload is inside data.

Field	Type	Description
`data`	object	The updated subscription.
`data.id`	integer	The subscription's id (`webhookSubscriptionId`).
`data.partner_company_id`	integer	Your partner id.
`data.label`	string	Your name for the subscription.
`data.webhook_url`	string	Where deliveries are sent.
`data.events`	array of strings or null	The event filter. `null`: all immediate events. Always `null` on a batch subscription.
`data.payload_mode`	string	`full` (the review, who did it, and the history entry) or `minimal` (event name and ids only). Always `full` on a batch subscription.
`data.delivery_kind`	string	`immediate` (each event as it happens) or `batch` (one `cache_invalidation` ping per location per interval).
`data.batch_interval_hours`	integer or null	Hours between batches: `1`, `2`, `4`, `6` or `12`. `null` on an immediate subscription.
`data.delivery_label`	string	The delivery type in words: `immediate`, `hourly batch` or `every N hours`.
`data.last_batch_dispatched_at`	string or null	When the last batch was sent (ISO 8601). Set to the creation time for a new batch subscription; `null` on an immediate one.
`data.is_active`	boolean	Whether deliveries are being sent.
`data.hmac_secret_fingerprint`	string	The first 16 characters of the SHA-256 hash of the signing secret, so you can tell which secret is current. The secret itself is never returned here.
`data.last_succeeded_at`	string or null	When a delivery last succeeded (ISO 8601), or `null`.
`data.last_failed_at`	string or null	When a delivery last failed (ISO 8601), or `null`.
`data.last_failure_reason`	string or null	Why the last delivery failed, or `null`.
`data.consecutive_failure_count`	integer	Failed deliveries in a row since the last success.
`data.created_at`	string	When the subscription was created (ISO 8601).
`data.updated_at`	string	When it last changed (ISO 8601).

Response payload

{
  "data": {
    "data": {
      "id": 3,
      "partner_company_id": 5,
      "label": "Updated webhook label",
      "webhook_url": "https://partner.example.com/hooks/sau-v2",
      "events": null,
      "payload_mode": "minimal",
      "delivery_kind": "immediate",
      "batch_interval_hours": null,
      "delivery_label": "immediate",
      "last_batch_dispatched_at": null,
      "is_active": true,
      "hmac_secret_fingerprint": "335b947fe611b6b2",
      "last_succeeded_at": null,
      "last_failed_at": null,
      "last_failure_reason": null,
      "consecutive_failure_count": 0,
      "created_at": "2026-06-16T10:25:29+00:00",
      "updated_at": "2026-06-16T10:26:02+00:00"
    }
  }
}

Examples

Success payload

See Response payload.

Error payload

403 Not a Partner token

{
  "message": "Only partner-admin users can manage webhook subscriptions.",
  "status": "error",
  "errors": []
}

404 Subscription not found

{
  "message": "Subscription not found.",
  "status": "error",
  "errors": []
}

422 Invalid values

{
  "message": "The label field is required. (and 1 more error)",
  "errors": {
    "label": [
      "The label field is required."
    ],
    "webhook_url": [
      "The webhook url field must be a valid URL."
    ]
  }
}

422 You already have one of this kind

{
  "message": "A batch webhook already exists for this partner. Switch the other slot first.",
  "errors": {
    "delivery_kind": [
      "A batch webhook already exists for this partner. Switch the other slot first."
    ]
  }
}

Status	Meaning
`200`	The subscription was updated.
`401`	The token is missing, expired or invalid.
`403`	The token isn't a Partner token.
`404`	No subscription with this id belongs to your partner.
`422`	A field is invalid, an event can't be picked, or you already have a subscription of the new kind.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/partner/webhooks/3/update" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"label": "Updated webhook label", "webhook_url": "https://partner.example.com/hooks/sau-v2", "is_active": true, "payload_mode": "minimal"}'