# Set the default alerts

Choose who is mailed, and which webhook is called, when a project gets a new issue, a regression, or an ignored issue that comes back.

Every project alerts on its own. For other conditions, filters, or Teams and Discord formats, add
an alert rule (see [Create an alert rule](create-an-alert-rule.md)). Replace _project-id_ with the
project's id.

## When the default alerts fire

- A new issue.
- A regression: a resolved issue gets an event again. An issue resolved in the next release
  regresses only on an event from a newer release (or a release the project has not seen).
- An ignored issue comes back once its time or event count has passed.

At most one default alert per issue every 30 minutes. An alert follows the event within seconds.

With **Only environments** set, the default alerts fire only when the events that caused them are
from one of those environments. Events that name no environment then never alert. Set it to
`production` when staging and production share the project, so production's on-call is never
paged by staging.

## Prerequisites

- Permission for `errors:UpdateProject` on the project. Without it, the console shows the settings
  read-only, with the note "Changing settings needs errors:UpdateProject on this project."
- In the console, also `errors:ListProjects` on the project to open it (without it the project is
  not found).

## Change the recipients

| Setting                                   | A new project | Values             |
| ----------------------------------------- | ------------- | ------------------ |
| Mail the organization's owners and admins | on            | on or off          |
| Also mail                                 | none          | up to 20 addresses |
| Webhook                                   | none          | one `https://` URL |
| Only environments                         | none (any)    | up to 20 names     |

**Console**
1. Open the project, then the **Settings** tab.
2. Under **Default alerts**, turn **Mail the organization's owners and admins** on or off.
3. For **Also mail**, enter addresses, separated by commas.
4. For **Webhook**, enter an `https://` URL.
5. For **Only environments**, enter environment names, separated by commas, or leave it empty for
   any.
6. Choose **Save**. It saves the whole form, the project's other settings included.

**CLI**
```sh
dcloud errors projects update project-id --alert-email-addresses oncall@example.com \
  --alert-webhook-url https://hooks.slack.com/services/T000/B000/XXXX
```

**API**
```http
PATCH /errors/api/projects/project-id
{ "alertEmail": true, "alertEmailAddresses": ["oncall@example.com"], "alertWebhookUrl": "https://hooks.slack.com/services/T000/B000/XXXX" }
```

`alertEmailAddresses` replaces the list. `"alertEnvironments": ["production"]` limits the default
alerts to production's events; `[]` alerts for any. `"alertWebhookUrl": null` removes the webhook. An `http://`
URL is refused with `400`.

**Terraform**
```hcl
resource "dcloud_errors_project" "web" {
  name                  = "web"
  alert_email           = true
  alert_email_addresses = ["oncall@example.com"]
  alert_webhook_url     = "https://hooks.slack.com/services/T000/B000/XXXX"
}
```

## What the webhook receives

A `POST` with JSON. A Slack incoming-webhook URL (`hooks.slack.com`) gets Slack's message format;
any other URL gets this, with `type` `ews.errors.issue.created`, `ews.errors.issue.regressed` or
`ews.errors.issue.escalating`:

```json
{
  "type": "ews.errors.issue.created",
  "issue": {
    "id": 74,
    "shortId": "WEB-22",
    "title": "TypeError: Cannot read properties of undefined",
    "culprit": "/checkout",
    "location": "src/cart.ts in totalOf",
    "level": "error",
    "status": "unresolved",
    "count": 1,
    "userCount": 1,
    "firstSeen": "2026-11-18T09:00:00.000Z",
    "lastSeen": "2026-11-18T09:00:00.000Z",
    "release": "1.2.3",
    "environment": "production",
    "url": "https://console.example.com/errors/issues/74"
  },
  "project": { "id": "…", "slug": "web", "name": "web" }
}
```

The default webhook is not signed. It is posted once, to port 443 of a public address; it does not
follow redirects, and a webhook or mail that fails is not retried.

## Related

- [Create an alert rule](create-an-alert-rule.md)
- [Issues and grouping](issues-and-grouping.md)
- `errors.projects.update` · `dcloud_errors_project`
