# Manage subscribers

Add a webhook or invite an email address to a status page's updates, see who subscribed, and remove a subscriber.

Subscribers hear about every incident posted, updated or resolved, and about a component that
follows a check going down and coming back. Replace _page-id_ with the status page's id and
_subscriber-id_ with the subscriber's.

- **Email.** Visitors enter their address on the page, and you can invite one. Nothing is sent but a
  confirmation link until the address opens it; an address still unconfirmed a day after it was added
  is removed by the next daily cleanup.
  Every mail has an unsubscribe link.
- **Webhook.** Only you add one: an `https://` URL on a public address, confirmed at once. For its
  body, see [Notification webhooks](notification-webhooks.md).

## Prerequisites

- Permission for `monitoring:UpdateStatusPage` on the page,
  `rn:ews::<organization id>:monitoring:status-page/<page id>`, to add or remove one, and
  `monitoring:DescribeStatusPages` to list them.

## Add a subscriber

**Console**
1. Open **Monitoring**, then **Status pages**, and choose the page.
2. Under **Subscribers**, choose **Webhook** or **Email**, and enter the URL or the address.
3. Choose **Add**.

An address shows **not confirmed** until its link is opened.

**CLI**
```sh
dcloud monitoring subscribers add page-id --kind webhook \
  --target https://hooks.example.com/status
```

**API**
```http
POST /monitoring/api/status-pages/page-id/subscribers
{ "kind": "email", "target": "jane.doe@example.com" }
```

**Terraform**
```hcl
resource "dcloud_status_page_subscriber" "chatops" {
  status_page_id = dcloud_status_page.acme.id
  kind           = "webhook"
  target         = "https://hooks.example.com/status"
}
```

Changing any argument replaces the subscriber.

## Remove a subscriber

In the console, choose the subscriber's remove button. With the CLI or the API:

```sh
dcloud monitoring subscribers remove page-id subscriber-id
```

```http
DELETE /monitoring/api/status-pages/page-id/subscribers/subscriber-id
```

## When the subscriber is refused

- `409` "Already subscribed" for a target the page already has.
- `409` "A status page has at most 1000 subscribers".
- `400` when the address is not an email address, or the webhook URL is not allowed.

On the public page, the form answers "Too many subscriptions from here; try again later." after 10
subscriptions in an hour from one network address, after 100 in an hour to the page, and when the
page has 1000 subscribers. Text that is not an email address answers "That link is not valid any
more.". Otherwise it answers "Check your inbox: we sent a link to confirm the subscription.", also
for an address that was already subscribed (which is sent nothing).

## Related

- [Post an incident](post-an-incident.md)
- [Notification webhooks](notification-webhooks.md)
- `monitoring.subscribers.add` · `dcloud_status_page_subscriber`
