Webhooks

DevHelm supports two webhook systems:

Alert channel webhooks — incident notifications routed through notification policies (this page)
Platform event webhooks — subscribe to specific event types for broader automation (see API Reference)

Alert channel webhooks

Send incident notifications to any HTTP endpoint.

Setup

devhelm alert-channels create \
  --name "Custom Webhook" \
  --type webhook \
  --config '{"channelType":"webhook","url":"https://your-app.example.com/webhooks/devhelm","signingSecret":"my-hmac-secret"}'

alertChannels:
  - name: Custom Webhook
    config:
      channelType: webhook
      url: https://your-app.example.com/webhooks/devhelm
      signingSecret: ${WEBHOOK_SIGNING_SECRET}
      customHeaders:
        X-Source: devhelm

Configuration

Field	Description	Required
`url`	Webhook endpoint URL (HTTP or HTTPS)	Yes
`signingSecret`	HMAC signing secret for payload verification	No
`customHeaders`	Additional HTTP headers to include	No

Custom headers cannot use the X-DevHelm-* prefix or override Content-Type.

Verifying signatures

When a signing secret is configured, DevHelm includes a signature header:

X-DevHelm-Signature: t=1712956800;v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

To verify:

Extract the t (timestamp) and v1 (signature) values
Compute HMAC-SHA256(signingSecret, t + ":" + requestBody)
Compare the computed signature with v1
Optionally reject requests where t is too old (replay protection)

The signed string uses a literal colon (:) between the timestamp and the raw request body — no quoting, no escaping. Use the raw bytes of the HTTP request body (do not re-serialise the parsed JSON, since key ordering or whitespace would change the hash).

Platform event webhooks

For broader event coverage beyond incident notifications, use the platform webhook system at /api/v1/webhooks.

Available event types

Monitoring events:

monitor.created, monitor.updated, monitor.deleted
incident.created, incident.resolved, incident.reopened

Status data events:

service.status_changed, service.component_changed
service.incident_created, service.incident_updated, service.incident_resolved

Envelope format

Every platform event webhook delivery POSTs the following envelope as the request body:

{
  "id": "11111111-1111-1111-1111-111111111111",
  "type": "incident.created",
  "apiVersion": "2026-01",
  "createdAt": "2026-04-24T12:34:56Z",
  "data": {
    // Event-specific payload
  }
}

id — unique event ID. Use this for idempotent processing: the same id is sent on every retry, so receivers can deduplicate by storing IDs they’ve already processed.
type — event type identifier (matches the X-DevHelm-Event header).
apiVersion — pinned envelope/payload version. Increments only when the schema changes incompatibly. Receivers should branch on this value if they need to support multiple versions during a migration.
createdAt — UTC timestamp (ISO 8601 with Z suffix) of when DevHelm originated the event.
data — the event-specific payload. Shape depends on type.

Outgoing headers

Header	Description
`X-DevHelm-Event`	Event type (e.g., `incident.created`)
`X-DevHelm-Delivery`	Unique delivery ID
`X-DevHelm-Signature`	`t=<timestamp>;v1=<hmac-sha256>`

Managing webhook endpoints

# Create a webhook endpoint
curl -X POST https://api.devhelm.io/api/v1/webhooks \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/events",
    "subscribedEvents": ["incident.created", "incident.resolved"]
  }'

# Test a webhook
curl -X POST https://api.devhelm.io/api/v1/webhooks/<id>/test \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN"

# List deliveries
curl https://api.devhelm.io/api/v1/webhooks/<id>/deliveries \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN"

Troubleshooting

Webhook deliveries failing

Check that your endpoint returns a 2xx status code within the timeout
Review delivery history: GET /api/v1/webhooks/<id>/deliveries
Verify your endpoint accepts POST requests with Content-Type: application/json

Signature verification failing

Make sure you’re using the correct signing secret
Use the raw request body for HMAC computation (before any JSON parsing)
The signature format is t=<unix-timestamp>;v1=<hex-hmac> — parse both values

Overview

Alert Channels

CI/CD

Alert channel webhooks

Setup

Configuration

Verifying signatures

Platform event webhooks

Available event types

Envelope format

Outgoing headers

Managing webhook endpoints

Troubleshooting

​Alert channel webhooks

​Setup

​Configuration

​Verifying signatures

​Platform event webhooks

​Available event types

​Envelope format

​Outgoing headers

​Managing webhook endpoints

​Troubleshooting

Alert channel webhooks

Setup

Configuration

Verifying signatures

Platform event webhooks

Available event types

Envelope format

Outgoing headers

Managing webhook endpoints

Troubleshooting