> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corelayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom alerts

> Send JSON alerts to Corelayer using a webhook URL and bearer token.

Send alerts from a monitoring tool that supports the JSON format below. For incident.io, CloudWatch, Datadog, or Honeycomb, start with the [matching webhook type](/webhooks/overview#add-a-webhook).

## Prerequisites

You need permission to add webhooks in Corelayer and a tool that can POST JSON to the webhook URL.

## Setup

### 1. Create a source

Open **Webhooks** and click **Add Webhook**. Set **Webhook type** to **Custom Webhook**, enter a **Source name** such as `Checkout alerts`, and click **Create Webhook**.

Copy the **Webhook URL**, **Webhook token**, and **Example request**. The token is shown once, so store it before clicking **Done**.

### 2. Configure your alert sender

Set your monitoring tool to POST the [JSON alert payload](#alert-payload) to the webhook URL with these headers:

```text theme={null}
Authorization: Bearer <your-token>
Content-Type: application/json
```

The URL must be reachable from the sender. For customer-hosted Corelayer, a private URL works when the sender is on the same network. Cloud-hosted senders need access from their own network.

### 3. Send an example alert

Run the example `curl` request from a machine that can reach the endpoint. Use the current timestamp when sending a new example.

This sends a real alert and can start an investigation. A `202` response means the request was accepted; read its `status` field to see whether it was queued, ignored as a duplicate, or skipped. For a queued alert, check Corelayer for the resulting investigation.

## Alert payload

Send one alert per request. Use the alert's actual timestamp for `time`:

```json theme={null}
{
  "id": "checkout-500-rate",
  "action": "trigger",
  "time": "2026-09-09T12:00:00Z",
  "name": "Checkout API 500 rate is elevated",
  "message": "5xx rate crossed 5% for checkout-api",
  "severity": "high",
  "source": "checkout-monitor",
  "fingerprint": "checkout-api:5xx-rate:prod",
  "labels": {
    "service": "checkout-api",
    "environment": "prod"
  }
}
```

### Required fields

| Field     | Description                                                                     |
| --------- | ------------------------------------------------------------------------------- |
| `id`      | Alert identifier from your monitoring tool                                      |
| `action`  | `trigger`, `resolve`, or `acknowledge`                                          |
| `time`    | Alert timestamp as a valid date string; use RFC 3339, such as the example above |
| `name`    | Short alert name                                                                |
| `message` | Alert message or summary                                                        |

### Optional fields

| Field         | Description                                                                     |
| ------------- | ------------------------------------------------------------------------------- |
| `description` | Longer alert details                                                            |
| `severity`    | `critical`, `high`, `medium`, `low`, or `info`. Defaults to `info` when omitted |
| `source`      | Name of the monitoring tool                                                     |
| `sourceUrl`   | URL of the alert in the monitoring tool                                         |
| `fingerprint` | Stable key used to identify repeated alerts                                     |
| `labels`      | Key-value labels such as service, environment, or region                        |

### Map your payload

If your tool supports a custom payload template, map its fields to this format. Set `action` to `trigger` when the alert fires and `resolve` when it recovers. Use a stable `fingerprint` for repeated notifications of the same alert.

Omit optional fields that have no value. For example, `severity: ""` is invalid; omit `severity` to use `info`.

## How alerts are handled

* `trigger` sends the alert for investigation.
* Repeated triggers with the same fingerprint are accepted but ignored during the deduplication window.
* `resolve` and `acknowledge` are recorded but do not automatically close Corelayer issues.

See [Manage sources](/webhooks/overview#manage-sources) to change or remove this source.

## Troubleshooting

### The sender cannot reach the endpoint

Check the URL and network access from the system sending alerts. For a private deployment, test from that network rather than your laptop.

### The endpoint returns an error

| Response | Check                                                                                                    |
| -------- | -------------------------------------------------------------------------------------------------------- |
| `400`    | Read the response detail. Check the JSON, required fields, and allowed `action` and `severity` values    |
| `401`    | Check the bearer token and `Authorization` header. If the token is lost, rotate it and update the sender |
| `403`    | The webhook is disabled                                                                                  |
| `404`    | Check the exact URL and confirm the webhook still exists                                                 |

### No investigation starts

Read the response's `status`. A duplicate trigger is ignored, and resolution or acknowledgement events are only recorded. If it reports `skipped_onboarding`, complete your organization's onboarding and send a new alert.

Need help? [Contact support](mailto:support@corelayer.com).


## Related topics

- [Corelayer Changelog: May 2026 Release](/changelog/may-2026.md)
- [Overview](/webhooks/overview.md)
- [August 2026](/changelog/august-2026.md)