Update a webhook subscription
BuildingIn development for the v1 API. The contract is set; the route is not served yet.
Changes only the fields sent. status: paused holds the deliveries that are waiting; status: active resumes them and releases the held ones, also when heru disabled the subscription. A validation that fails changes nothing.
Needs the webhooks:write scope.
oauth2 webhooks:writeAuthorizationBearer <token>OAuth 2.0 client credentials. Exchange your client_id and client_secret at /oauth/token of the environment for a bearer token valid for one hour. The playground of every operation asks for your own client and keeps it in your browser tab only.
Scope: webhooks:write
id*stringThe subscription id.
^whk_[0-7][0-9a-hjkmnp-tv-z]{25}$application/json- body
Every field is optional; only the fields sent change. headers replaces the whole set: [] removes them all.
url?stringurilength <= 2048event_types?array<string>1 <= items <= 20merchant_ids?array<>items <= 100description?stringlength <= 500headers?array<>items <= 5status?stringpaused stops deliveries and holds them; active resumes them and releases the held ones, also after heru disabled the subscription.
"active""paused"The subscription as it is now, without secret.
application/json- response
id*string^whk_[0-7][0-9a-hjkmnp-tv-z]{25}$url*stringuridescription*stringevent_types*array<string>merchant_ids*array<>status*stringactive delivers; paused you set it and deliveries wait; disabled heru set it (see disabled_reason) and deliveries wait until you send status: active.
"active""paused""disabled"disabled_reason*|nulldisabled_at*|nullheaders*array<>secret?stringOnly in the answer of POST /webhooks and POST /webhooks/{id}/secret. Store it: it is never shown again.
^whsec_[A-Za-z0-9_-]{43}$secret_last4*stringsecret_rotating_until*|nullconsecutive_failures*integerFailed deliveries in a row. A 2xx resets it to zero.
failing_since*|nullenvironment*string"sandbox""production"created_at*stringdate-timeupdated_at*stringdate-timedeliveries*Where the delivery log of this subscription is.
curl -X PATCH 'https://api.dev.b2b.heru.app/v1/webhooks/whk_01m53g5zw414zt6vg08fqbacgm' \ -H 'Content-Type: application/json' \ -d '{ "status": "paused", "description": "POS production (maintenance window)"}'{ "id": "whk_01m53g5zw414zt6vg08fqbacgm", "url": "https://partner.example.com/heru/webhooks", "description": "POS production (maintenance window)", "event_types": [ "invoice.stamped", "charge.invoiced" ], "merchant_ids": [ "mer_01m4ra8wsyfh3s0tr4nrq3y96j" ], "status": "paused", "disabled_reason": null, "disabled_at": null, "headers": [ { "name": "X-Partner-Token", "value": "****abcd" } ], "secret_last4": "L2Do", "secret_rotating_until": null, "consecutive_failures": 0, "failing_since": null, "environment": "production", "created_at": "2026-10-25T12:00:00.000Z", "updated_at": "2026-10-26T09:12:00.000Z", "deliveries": { "path": "/v1/webhooks/whk_01m53g5zw414zt6vg08fqbacgm/deliveries" }}Replay a deliveryPOST
Queues a new delivery of the same event, byte for byte, to the same subscription. It goes out on the next pass with its own `Heru-Delivery-Id` and `Heru-Attempt: 1`; discard it by `Heru-Event-Id` if you already processed the event. Allowed for `delivered`, `failed` and `expired` deliveries whose event is still retained (30 days); a delivery in progress or of a deleted subscription answers `409`. Retrying with the same `Idempotency-Key` returns the same new delivery. Needs the `webhooks:write` scope.
Delete a webhook subscriptionDEL
Stops every delivery to it: the deliveries still waiting to be sent expire. The delivery log stays readable for 30 days. Needs the `webhooks:write` scope.