Skip to main content

​
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; 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. 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: 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 for DLQ replay.
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.

​
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, 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. 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