Custom Webhook Integration

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:

Authorization: Bearer <your-token>

Set the request content type to JSON:

Content-Type: application/json

Alert Payload Format

Custom Webhook expects a canonical JSON alert payload.

{
  "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

Mapping a Provider’s Native Payload

Some alerting tools send their own payload shape and reject arbitrary bodies. For those, use the tool’s custom payload template to emit the canonical fields above. Two rules cover most providers: map the provider’s firing/recovery state onto action (trigger when firing, resolve when recovered), and format the timestamp as an RFC 3339 string.

Honeycomb

Honeycomb Triggers send a native payload, so point the trigger at a webhook recipient and set a custom payload template. In the Honeycomb recipient’s Payload template for trigger notifications:

{
  "id": "{{ .Alert.InstanceID }}",
  "action": "{{ if eq .Alert.Status "TRIGGERED" }}trigger{{ else }}resolve{{ end }}",
  "time": "{{ .Alert.Timestamp | date "2006-01-02T15:04:05Z07:00" }}",
  "name": "{{ .Name }}",
  "message": "{{ if .Alert.Summary }}{{ .Alert.Summary }}{{ else }}{{ .Name }} {{ .Operator }} {{ .Threshold }}{{ end }}",
  "description": "{{ .Description }}",
  "severity": "high",
  "source": "honeycomb",
  "sourceUrl": "{{ .Result.URL }}",
  "fingerprint": "{{ .ID }}"
}

Add the webhook’s bearer token as an Authorization header on the recipient. The {{ if eq .Alert.Status "TRIGGERED" }} mapping sends trigger when the trigger fires and resolve when it recovers, and the date format keeps time a valid RFC 3339 string. The trigger’s .ID stays stable across firings, so it groups repeated alerts through fingerprint. Use Honeycomb’s Send Test on the trigger to confirm the webhook accepts the payload before relying on it.

Grafana

Grafana’s webhook contact point sends a fixed payload, so use its Optional Webhook Settings → Custom payload to emit the canonical fields. A Grafana notification batches the alerts in a group into one request; this template maps the group to a single canonical alert:

{
  "id": "{{ .GroupKey }}",
  "action": "{{ if eq .Status "firing" }}trigger{{ else }}resolve{{ end }}",
  "time": "{{ (index .Alerts 0).StartsAt.Format "2006-01-02T15:04:05Z07:00" }}",
  "name": "{{ .CommonLabels.alertname }}",
  "message": "{{ .CommonAnnotations.summary }}",
  "description": "{{ .CommonAnnotations.description }}",
  "severity": "{{ .CommonLabels.severity }}",
  "source": "grafana",
  "sourceUrl": "{{ (index .Alerts 0).GeneratorURL }}",
  "fingerprint": "{{ .GroupKey }}"
}

Add the bearer token under the contact point’s HTTP Headers as Authorization: Bearer <your-token>. .Status maps firing to trigger and resolved to resolve; .GroupKey is stable per alert group, so it dedupes repeated notifications through fingerprint. .CommonLabels.severity is passed through when your alert rule sets a severity label, and defaults to info otherwise. Send a test notification from the contact point to confirm the payload is accepted.

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. When the sender is a tool with its own payload shape, such as Honeycomb or Grafana, map its native fields to the canonical schema with a custom payload template — see Mapping a Provider’s Native Payload. Need help? Contact support for assistance with your Custom Webhook integration.

Get Started

Anomaly Detection

Organization Memory

Security & Privacy

Integrations

Developer Tools

Custom Webhook Integration

Prerequisites

Step-by-Step Setup

1. Navigate to Integrations

2. Add Custom Webhook

3. Copy the Webhook Details

4. Verify the Webhook

5. Configure Your Alert Sender

Alert Payload Format

Required Fields

Optional Fields

Mapping a Provider’s Native Payload

Honeycomb

Grafana

How Corelayer Handles Alerts

Managing Webhooks

Customer-Hosted Deployments

Troubleshooting

Verification Does Not Complete

Webhook Returns 401

Webhook Returns 403

Webhook Returns 400

​Prerequisites

​Step-by-Step Setup

​1. Navigate to Integrations

​2. Add Custom Webhook

​3. Copy the Webhook Details

​4. Verify the Webhook

​5. Configure Your Alert Sender

​Alert Payload Format

​Required Fields

​Optional Fields

​Mapping a Provider’s Native Payload

​Honeycomb

​Grafana

​How Corelayer Handles Alerts

​Managing Webhooks

​Customer-Hosted Deployments

​Troubleshooting

​Verification Does Not Complete

​Webhook Returns 401

​Webhook Returns 403

​Webhook Returns 400

Prerequisites

Step-by-Step Setup

1. Navigate to Integrations

2. Add Custom Webhook

3. Copy the Webhook Details

4. Verify the Webhook

5. Configure Your Alert Sender

Alert Payload Format

Required Fields

Optional Fields

Mapping a Provider’s Native Payload

Honeycomb

Grafana

How Corelayer Handles Alerts

Managing Webhooks

Customer-Hosted Deployments

Troubleshooting

Verification Does Not Complete

Webhook Returns 401

Webhook Returns 403

Webhook Returns 400