> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Edit a webhook subscription in the console
> Walk through the per-subscription edit console — open the Edit dialog from the Webhooks list, retune event filters, set the retry ladder and delivery timeout, rotate the signing secret, toggle the endpoint on or off, test-fire, and read the audit trail.
# Edit a webhook subscription in the console
Every setting on a registered webhook endpoint is editable in place from the dashboard — you never need to delete and recreate an endpoint to change it. Editing in place keeps the endpoint ID, the signing secret, and the full delivery history intact.
This page walks the per-subscription edit console end to end.
## 1. Where the edit console lives
Open the console at **Developer → Webhooks**. The list shows every endpoint in your tenant with its URL, subscribed event count, health, and active state.
Two surfaces work together here:
* **The Edit dialog.** Open the endpoint's overflow menu (⋯) on its row and choose **Edit**. The dialog pre-fills every current value: URL, subscribed events, description, agent scope, delivery timeout, custom headers, active state, and the signing-secret section.
* **The endpoint detail page.** Click the endpoint row to open its detail page — deliveries, health, replay, test-fire, and secret rotation. Those operations are covered step by step in [Operate a webhook endpoint](/guides/webhook-endpoint-operations); this guide covers the edit side.
Nothing applies until you click **Save Changes** in the Edit dialog. Closing the dialog without saving discards every pending edit.
## 2. Edit the event filter
The **Events** picker controls exactly which event types reach this endpoint.
* Events are grouped by category (Messages, Voice, Agents, and so on) in collapsible sections. Each section shows a selected/total counter, and a **Select all** per section toggles the whole category at once.
* Use the search box to filter the catalog by name — a global **Select all / Deselect all** above the picker toggles every event at once.
* At least one event must stay selected; the dialog refuses to save an empty subscription.
The picker lists the current event catalog. An endpoint that carries a retired event type — subscribed before that event left the catalog — keeps delivering it, and the dialog preserves it on save; you can narrow the subscription but never resurrect a retired event from the console. For the full catalog with payload shapes, see the [Webhook event catalog](/guides/webhook-event-catalog).
One thing the console cannot do per subscription is *transform* the payload — per-endpoint payload filtering and field mapping live on the API `transform` field. Everything else in this guide has a console control.
## 3. Retry ladder and delivery timeout
Two separate knobs decide how a failed delivery behaves. Both are per-endpoint and apply to the next delivery — in-flight attempts finish on their existing schedule.
**Delivery timeout** — how long the dispatcher waits for your receiver to answer before it counts the attempt as failed. Set it in the Edit dialog's **Delivery timeout** dropdown: the common presets are 5, 10, 15, 20, and 30 seconds. The platform ceiling is 30 seconds; if you set a non-preset value through the API (any whole number from 1 to 30), the dropdown shows it so a save never silently resets a tighter timeout to the default.
**Retry ladder** — how many times a failed delivery is re-attempted and how long the dispatcher waits between attempts. The ladder is configured through the API on `retry_policy`:
| Field | Range | Meaning |
| ------------------ | ------------------------ | ---------------------------------------- |
| `max_retries` | 0–10 | Attempts after the first delivery fails. |
| `backoff_strategy` | `fixed` \| `exponential` | Spacing between attempts. |
| `initial_delay_ms` | 100–86,400,000 | First backoff interval in milliseconds. |
With `exponential` backoff the delay between attempts doubles from `initial_delay_ms` each round; `fixed` retries on the same interval every time. Once the ladder is exhausted, the delivery lands in the dead-letter queue, where you can inspect it and replay it — see [Operate a webhook endpoint](/guides/webhook-endpoint-operations) for DLQ replay.
```bash theme={null}
curl -X PUT "https://api.orbit.devotel.io/api/v1/webhooks/whp_9d2e4f" \
-H "X-API-Key: dv_live_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{"retry_policy": {"max_retries": 5, "backoff_strategy": "exponential", "initial_delay_ms": 5000}}'
```
```json 200 theme={null}
{
"data": {
"id": "whp_9d2e4f",
"retry_policy": {
"max_retries": 5,
"backoff_strategy": "exponential",
"initial_delay_ms": 5000
}
},
"meta": {
"request_id": "req_8f3a1c",
"timestamp": "2026-09-25T08:00:01.337Z"
}
}
```
Omit every member to reset the endpoint to the platform default ladder. Tune conservatively: a receiver with a cold-start problem wants a longer initial delay; a receiver behind a rate limiter wants fewer attempts with exponential spacing rather than a burst of fixed-interval retries.
## 4. Rotate the signing secret
Start a rotation from any of three places with the same result: the **Rotate** button in the Edit dialog's **Signing secret** section, the endpoint's overflow menu on the detail page, or the API.
While a rotation runs, a **Rotation in flight** badge appears in the Edit dialog and on the detail page header, and every delivery is dual-signed — the current secret and the candidate both produce valid signatures for the 7-day grace window, so a correctly configured verifier never misses a delivery during cutover.
1. Click **Rotate** to open the rotation wizard. **Continue** mints the candidate secret.
2. Copy the candidate into your verifier's configuration — it is shown exactly once.
3. Track progress on the status step: the share of recent deliveries verifying with the new secret, days left in the grace window, and whether **Complete rotation** is eligible yet. Clicking it retires the old secret. **Cancel rotation** burns the candidate and keeps the original.
The full flow — including the `X-Orbit-Signature-Next` grace-header contract your verifier must accept while a rotation runs — is documented in [Operate a webhook endpoint](/guides/webhook-endpoint-operations).
## 5. Enable or disable the endpoint
The **Active** switch in the Edit dialog stops deliveries without deleting anything:
* **Off** — the dispatcher stops queueing new deliveries to the endpoint. The endpoint, its secret, its retry policy, and its delivery history all stay put. In-flight attempts already queued complete on their existing schedule.
* **On** — delivery resumes immediately. Any failure-based auto-disable is cleared by the same toggle.
Disable when you need an open-ended stop (retiring a receiver, investigating a bug). For a bounded maintenance window, prefer **Pause** from the endpoint's overflow menu — it accepts an automatic resume time, so you cannot leave an endpoint asleep by mistake. Deleting the endpoint is the only destructive option: you lose the ID, the secret, and the history.
## 6. Test-fire from the console
Before or after any edit, prove the endpoint works with a signed test-fire. On the endpoint's detail page, **Test-fire event** sends a synthetic event through the real delivery pipeline, signed with this endpoint's secret — unlike the unsigned [Webhook Tester](/guides/webhook-tester), which fires at arbitrary URLs.
The button shows a live result chip with your receiver's actual status code and latency (polled every two seconds for up to 30 seconds), and the fired event lands in the deliveries table like any other attempt. A `401` or `403` on a test-fire almost always means signature verification failed at your receiver — work through [Verify webhook signatures](/guides/verify-webhook-signatures). The `?test=fire` query parameter on the detail page URL deep-links straight into the picker.
## 7. Audit history
Every console action in this guide writes an audit entry — subscription edits, active toggles, secret rotations (start, complete, cancel), pauses, resumes, and test-fires all record who acted, what changed, and when. Open the org audit log under **Settings → Audit** and filter by the webhook resource to reconstruct an endpoint's change history.
Delivery-level history is separate: the deliveries table on the detail page keeps every attempt with status and latency, and a rotation's status step tells you which secret recent deliveries verified against. Use the audit log to answer "who changed this endpoint and when"; use the deliveries table to answer "what did the receiver do with the traffic."
## 8. Screenshot sequence
Follow along in the console:
1. **Webhooks list** — the endpoint row with its health cell and active badge; the ⋯ overflow menu open on **Edit**.
2. **Edit dialog, top** — URL and description pre-filled, the event picker expanded to the Messages category with a partial selection counter.
3. **Edit dialog, middle** — agent scope, delivery-timeout dropdown open on the presets, and the custom-headers section with one `Authorization` row.
4. **Edit dialog, bottom** — the **Active** switch and the **Signing secret** section with its **Rotate** button.
5. **Rotation wizard** — the copy step showing the one-time candidate secret, then the status step reporting verification share and grace days.
6. **Detail page** — the header action group (test-fire, replay range, overflow) above the health panel and the deliveries table filtered to failed attempts.
## See also
* [Operate a webhook endpoint](/guides/webhook-endpoint-operations) — test-fire, replay, health, pause/resume on the detail page
* [Webhook Tester](/guides/webhook-tester) — unsigned test sends at arbitrary URLs before you register
* [Webhook event catalog](/guides/webhook-event-catalog) — every event type you can subscribe to
* [Verify webhook signatures](/guides/verify-webhook-signatures) — the checklist a signed test-fire exercises
* [Build a durable webhook consumer](/guides/webhook-consumer) — receiver correctness, including rotation grace headers