Webhook integrations

A webhook is an outbound HTTP request that Elerio sends to your URL when a monitor's state changes. It lets incidents reach PagerDuty, Slack, Mattermost or any receiver of your own.

The key difference from many services: the binding is to a specific monitor, not to the whole account. You can route production to PagerDuty and staging to a #noise Slack channel.

Creating an endpoint

In Notifications → Webhook, add an endpoint:

• Name — for yourself, to tell them apart in the list.
• URL — where to send requests.
• Secret — generated automatically (you can set your own). Used to sign requests — see below.

After creating it, bind the endpoint to the monitors you want via the channel selection in the monitor form. One endpoint can be bound to several monitors and vice versa.

The "Test" button sends a sample request immediately so you can verify your receiver.

Request format

Elerio sends a POST with a JSON body and these headers:

Header	Value
X-Elerio-Event	event type (for example, incident open/close)
X-Elerio-Webhook-Id	delivery identifier
X-Elerio-Delivery-Attempt	attempt number (starting at 1)
X-Elerio-Signature	signature sha256=<hex> (see below)

Verifying the signature

To be sure a request came from Elerio and wasn't forged, verify the signature. Elerio computes an HMAC-SHA256 of the request body with your secret and puts the result in the X-Elerio-Signature header as sha256=<hex>.

On your side, compute the HMAC of the raw body (before parsing JSON) with the same secret and compare the values — using a constant-time comparison.

import crypto from 'node:crypto';

function verify(rawBody, signatureHeader, secret) {
  const expected =
    'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature_header, expected)

If the signature doesn't match, reject the request.

Retries

If your receiver is unavailable or returns an error, Elerio retries delivery with growing backoff: roughly after 5 seconds, 30 seconds and 5 minutes. Once attempts are exhausted, the delivery is moved to a dead-letter queue and isn't retried again. Make your receiver idempotent — key off X-Elerio-Webhook-Id.

Security

The endpoint URL is checked when you create it: Elerio won't let webhooks target private or internal addresses. You can regenerate the secret at any time — the old one stops matching immediately.

Availability

The webhook channel is available from the Supporter plan (up to 5 endpoints); on Business and Enterprise the number of endpoints is unlimited. See Plans & limits.