> ## 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 Webhook Integration

> Send alerts from any monitoring tool to Corelayer using a generic webhook endpoint.

## Prerequisites

* Permission to add integrations in Corelayer
* A monitoring or alerting tool that can send HTTP POST requests
* Access to run `curl`, Postman, or another HTTP client from the same network as your alert sender

## Step-by-Step Setup

### 1. Navigate to Integrations

In your Corelayer dashboard, go to the **Integrations** page.

### 2. Add Custom Webhook

Click the **Add Integration** button and select **Custom Webhook** from the list of available integrations.

Enter a name for the alert source, such as `Grafana Production`, `Alertmanager`, or `Internal Monitor`.

### 3. Copy the Webhook Details

Corelayer will generate:

* A webhook URL
* A bearer token
* A sample alert payload
* A ready-to-copy `curl` command

The bearer token is shown during setup. Store it somewhere secure before closing the setup modal.

### 4. Verify the Webhook

Run the generated `curl` command from a machine that can reach the webhook endpoint. For customer-hosted Corelayer deployments, this can be a machine inside your private network.

Corelayer marks the webhook as verified after it receives a valid test request.

### 5. Configure Your Alert Sender

Configure your monitoring tool to send alert payloads to the webhook URL.

Include the bearer token in the `Authorization` header:

```text theme={null}
Authorization: Bearer <your-token>
```

Set the request content type to JSON:

```text theme={null}
Content-Type: application/json
```

## Alert Payload Format

Custom Webhook expects a canonical JSON alert payload.

```json theme={null}
{
  "id": "checkout-500-rate",
  "action": "trigger",
  "time": "2026-05-17T12:00:00Z",
  "name": "Checkout API 500 rate is elevated",
  "message": "5xx rate crossed 5% for checkout-api",
  "description": "Optional longer alert body",
  "severity": "high",
  "source": "grafana",
  "sourceUrl": "https://grafana.example.com/alerting/...",
  "fingerprint": "checkout-api:5xx-rate:prod",
  "labels": {
    "service": "checkout-api",
    "environment": "prod"
  }
}
```

### Required Fields

| Field     | Description                                          |
| --------- | ---------------------------------------------------- |
| `id`      | Unique alert identifier from your alerting system    |
| `action`  | Alert action: `trigger`, `resolve`, or `acknowledge` |
| `time`    | Alert timestamp as a valid date string               |
| `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` |
| `source`      | Name of the alerting system                                        |
| `sourceUrl`   | Link back to the alert in the source system                        |
| `fingerprint` | Stable deduplication key for repeated alerts                       |
| `labels`      | Key-value labels such as service, environment, region, or team     |

## How Corelayer Handles Alerts

When Corelayer receives a valid alert:

* `trigger` alerts start a Corelayer investigation.
* Duplicate `trigger` alerts with the same fingerprint are accepted but ignored for a short deduplication window.
* `resolve` and `acknowledge` alerts are accepted and recorded, but do not automatically close Corelayer issues yet.

## Managing Webhooks

You can create multiple Custom Webhook sources from the Custom Webhook integration page.

For each source, you can:

* Copy the webhook URL
* Reset the bearer token
* Reverify the webhook after a token reset
* Enable or disable the webhook
* Delete the webhook source

Disabling a webhook keeps its URL and token configuration in Corelayer, but Corelayer stops processing incoming alerts for that source until you enable it again.

## Customer-Hosted Deployments

For customer-hosted Corelayer deployments, the webhook URL should point to the Corelayer server in your environment.

The endpoint does not need to be publicly reachable if your alert sender is also inside your network. It only needs to be reachable from the system sending the alerts.

If you use a cloud-hosted alerting tool, such as Grafana Cloud or Datadog, make sure the webhook endpoint is reachable from that service.

## Troubleshooting

### Verification Does Not Complete

* Confirm the generated `curl` command was run against the exact webhook URL shown in Corelayer
* Confirm the bearer token was copied correctly
* Confirm your request includes `Content-Type: application/json`
* For private deployments, run the test from a machine that can reach the customer-hosted Corelayer server

### Webhook Returns 401

The bearer token is missing or incorrect. Reset the token in Corelayer, update your alert sender, and run the generated reverify command.

### Webhook Returns 403

The webhook may be disabled. Open the Custom Webhook integration page and enable the webhook source.

### Webhook Returns 400

The JSON payload is malformed or does not match the required alert schema. Check the required fields and supported `action` and `severity` values.

Need help? [Contact support](mailto:support@corelayer.com) for assistance with your Custom Webhook integration.