Webhooks

This page covers the public Subscribe and manage flows for outbound webhooks on your status dashboard. For URL rules, HMAC signing, admin registration, and suppression, see Outbound Webhooks. For JSON payload format and delivery logs, see Webhook notifications.

---

What visitors see

Webhook subscriptions let visitors register an HTTPS endpoint and receive a JSON event payload when matching events are created or updated.

On /subscribe, visitors with the webhook channel effectively enabled see a Webhook tab where they:

1. Enter an endpoint URL (HTTPS on port 443, reachable from the public internet).
2. Enter a management email used for verification, manage links, and delivery-failure alerts.
3. Select one or more components from your dashboard (grouped when component groups are enabled).
4. Accept consent and terms checkboxes.
5. Complete the reCAPTCHA check when the dashboard is public (SSO off).
6. Click Subscribe.

Endpoints must be absolute HTTPS URLs on port 443 — see Endpoint URL rules for validation details.

They must select at least one component to complete a new subscription. On public dashboards, Subscribe stays disabled until reCAPTCHA is completed.

Below the subscribe form, an Already subscribed? section lets returning managers enter their management email and click Manage to receive a link for updating preferences. The manage-request form also requires reCAPTCHA on public dashboards.

Double opt-in (verification)

Webhook subscriptions use double opt-in via the management email:

1. The visitor submits the subscribe form.
2. StatusDashboard stores a pending subscriber record and sends a verification email to the management address.
3. The visitor clicks the link in the email (/subscribe/verify?token=…).
4. The subscription is activated and the visitor is redirected to a management page.

Verification links expire after 24 hours. If a link expires, the visitor can submit the subscribe form again with the same endpoint (while still unverified).

On successful verification, the management page shows the signing secret once. See Signing for how to verify deliveries.

Managing preferences

After verification — or after requesting a manage link — visitors land on /subscribe/manage?token=…. The management token in the URL (valid for 1 hour) authorizes read and update operations on that endpoint's subscription. SSO does not replace this token — it only controls whether the visitor may reach the page in the first place.

On the manage page, visitors can:

• See the redacted endpoint display and management email (read-only).
• Add or remove component selections (deselecting all components stops notifications without deleting the subscription).
• Clear suppression after fixing a broken endpoint (Resume deliveries).
• Rotate the signing secret (webhook only).
• Return later via Manage on the subscribe page to receive a fresh link.

When a tenant admin has paused deliveries for this endpoint in the admin console, the manage page shows a read-only notice. Visitors cannot clear that pause from manage; they can still change component selections while paused.

Each new verification or manage-link email revokes any previous management link for that subscriber, so only the latest link is valid.

Pausing deliveries

Webhook subscriptions support pausing deliveries in a few different ways.

Admin pause, an empty component selection, and suppression are independent. Clearing suppression does not resume an admin pause.

Subscriber limits

• Each new unique endpoint consumes one slot at sign-up time (before verification completes).
• The same endpoint subscribing on a second status dashboard does not use an additional slot.
• When the org-wide limit is reached, new endpoints receive an error at submit time. Endpoints already in your organization may still subscribe on other dashboards.
• The Subscribe link remains visible; capacity is enforced when visitors submit the form.

If a visitor never completes verification, the pending record expires after 24 hours and the quota slot is released.

What admins control vs. what visitors control

Admin-managed endpoints are registered on Outbound webhook endpoints. Locked subscribers continue to receive notifications but cannot use the public subscribe or manage flows.

Security notes

• When SSO is enabled, visitors must authenticate through your IdP before using subscribe or manage APIs — the same gate as the rest of the dashboard. reCAPTCHA is not shown on SSO-protected dashboards.
• On public dashboards (SSO off), subscribe and manage-request forms require reCAPTCHA.
• Endpoint URLs often contain secrets. Treat manage links like password-reset links — do not share them.
• StatusDashboard never shows the full endpoint URL after create in list views; only a redacted display form is shown.
• IP allowlist rules still apply to subscribe traffic when configured.