Operate a webhook endpoint
Everything you do to keep a registered endpoint healthy lives on its detail page in the dashboard: fire signed test events and watch the receiver’s actual response, rotate the signing secret with a guided wizard, read endpoint health, and replay deliveries one at a time or in bulk.
Open a detail page by clicking an endpoint under Settings → Webhooks.
1. Read the endpoint health panel
The health panel at the top of the detail page aggregates the last 24 hours of real deliveries:
- Success rate — share of deliveries that got a 2xx from your receiver.
- Latency — p50 / p95 — receiver response times for the same window.
- Color band — green, amber, or red, derived from success rate and week-over-week degradation so a bad day is flagged even when absolute numbers look fine.
- Last 5 errors — the status code and response body your receiver returned on the most recent failures.
Check the panel before anything else: a red or amber band plus a recent error body usually names the problem directly.
Below the health panel, the Deliveries table lists delivery attempts for this endpoint, newest first, with the event type, event ID, HTTP status, and latency per attempt. Filter it to Errors only, Retrying now (failed rows still inside the automatic retry pipeline), or Slow (high latency rows). Select a row to inspect the exact payload and the full response.
2. Fire a signed test event
The Test-fire event control in the page header sends a synthetic event through the real delivery pipeline — unlike the console-wide Webhook Tester, which fires unsigned sends at arbitrary URLs. The test-fire signs with this endpoint’s secret, so it exercises your production verification logic end to end.
- Optionally pick a payload variant — success (complete happy-path payload), failure (failure status fields and an error message set), or minimal (optional fields stripped, for handlers written against only the required schema).
- Open the Test-fire event dropdown and pick an event type.
- The button shows a live result chip —
success or failed with the HTTP status and latency, once your receiver answers; the delivery row is polled every two seconds for up to 30 seconds before the chip reports a timeout.
- Expand the sample-payload panel under the button to see the exact envelope that was delivered — the shape that did (or did not) pass your checks.
A 401 or 403 result most often means signature verification failed on that event — the signed test-fire exercises your production verification path end to end. Work through the checklist in Verify webhook signatures, and make sure your verifier reads the raw body and compares timing-safe.
When the deliveries table is empty, a Send a test event action appears in the empty state too, opening the same picker — the URL …/webhooks/<id>?test=fire deep-links here as well.
3. Rotate the signing secret in the console
Open the Rotate secret dialog from the detail page (or from the endpoint’s overflow menu). The wizard mints a new secret while the old one keeps verifying deliveries — receivers accept both during the grace window, so rotation has no downtime if you follow it in order.
Step 1 – Confirm. The dialog explains the grace window and that minting a candidate secret cannot be undone. Click Continue to mint.
Step 2 – Copy. The new secret is shown once. Reveal it with Copy, paste it into your verifier’s configuration, tick the confirmation checkbox, and advance. If you close the dialog, this candidate is gone and you start over.
Step 3 – Status. The dialog polls rotation status and reports:
- the share of recent deliveries that verified with the new secret,
- how many days remain in the grace window,
- whether the rotation is eligible to auto-complete.
When your verifier runs on the new secret, most deliveries verify with it, and Complete rotation activates. Clicking it retires the old secret. Owners/admins can Force complete before the eligibility threshold when they’re sure the cutover is done. Cancel rotation burns the candidate and keeps the original secret — only use it when your verifier has not switched to the new secret yet.
If you open the dialog on an endpoint with an in-flight rotation, it resumes directly on the status step.
Verify the rotation works by following the correctness checklist in Build a durable webhook consumer — your verifier must accept the X-Orbit-Signature-Next header while a rotation is in flight.
4. Replay one delivery, or bulk-replay a failed batch
Single delivery. In the Deliveries table, open a failed row and click Replay — the original payload is re-POSTed to your endpoint. A successful re-delivery confirms the endpoint is healthy again.
Bulk replay. When a batch failed — a deploy outage, a bad signature config, a receiver bug — click Replay deliveries by range in the page header. In the dialog:
- Pick a date range and (optionally) an event type filter.
- Run the dry-run preview — the dialog shows how many deliveries match before you commit.
- Confirm. A replay job drives the matched deliveries with bounded concurrency and reports progress until every row is re-attempted.
Replay sends the original payload as stored; newer versions of the event are included only if the filter includes them.
Failed events across endpoints. The Developer → Webhooks → Events page lists every event with a status filter (delivered, failed, pending). Open a failed event and click Replay in its detail sheet to re-drive it; the sheet also shows the complete retry history — every attempt in chronological order — so you see how each attempt failed before re-driving.
5. Pause, rotate, or recreate?
- Pause when your receiver needs a maintenance window. The one-click Pause on the endpoint stops the dispatcher from delivering to it while keeping the configuration and delivery history — no events land during the pause, and Resume reactivates delivery. For automatic reactivation, the API accepts a bounded window (
duration_minutes or an explicit until timestamp) on POST /webhooks/:id/pause, so you can’t leave a paused endpoint behind by mistake.
- Rotate when the secret may be exposed or you’re following a rotation schedule. The endpoint, its event-type subscriptions, and its delivery history all stay intact — only the secret changes.
- Deactivate (set the endpoint inactive) for an open-ended stop. Deactivation, not pause, is what you want when you’re retiring the endpoint but keeping its history. Rotation works on inactive endpoints too.
- Recreate (delete + create) when the endpoint URL or the subscribed event types need to change. You get a fresh secret either way; recreating also means deliveries during the gap are dropped instead of queued.
See also
