# Webhooks

Let visitors subscribe a JSON webhook on your status dashboard.

Source: https://statusdashboard.com/docs/status-dashboards/subscriptions/webhooks

> This is a plan-gated feature. If it isn't available in your account, visit the [Billing](/docs/org-mgmt/billing) page or contact support to review your options.

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](/docs/integrations/webhooks/outbound). For JSON payload format and delivery logs, see [Webhook notifications](/docs/notifications/webhooks).

***

## 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](/docs/integrations/webhooks/outbound#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](/docs/integrations/webhooks/outbound#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.

| Who                        | How deliveries stop                                                                                                                                                         |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tenant admin**           | **Pause deliveries** in the admin console ([Managing subscribers](/docs/integrations/webhooks/outbound#managing-subscribers)). Component selections stay unchanged.         |
| **Visitor (manage page)**  | Deselect all components and save.                                                                                                                                           |
| **Platform (suppression)** | After repeated delivery failures ([Suppression](/docs/integrations/webhooks/outbound#suppression)). Use **Resume deliveries** on the manage page after fixing the endpoint. |

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
| Setting                                   | Controlled by                                                                                        |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Whether webhook subscriptions are offered | Plan (**integrations**) + dashboard **Subscriptions** tab toggle                                     |
| Which components an endpoint watches      | Visitor (at subscribe or on manage page), unless the subscription is **admin-managed (locked)** |
| Pause deliveries (integration flag)       | Tenant admin only — see [Pausing deliveries](#pausing-deliveries) above                              |
| Admin-managed (locked) subscriptions      | Admin — [Outbound Webhooks](/docs/integrations/webhooks/outbound#managing-subscribers)               |

**Admin-managed** endpoints are registered on [Outbound webhook endpoints](/app/integrations/webhooks/outbound/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.