Signed Webhooks for Your Own Systems

Endpoint requirements

• The URL must use https://.
• It must answer directly with a 2xx status. Redirects are not followed, so give SutramX the final URL.
• Respond quickly and do the heavy work asynchronously. Anything other than a 2xx counts as a failed delivery.

The signing secret

When you connect a webhook, SutramX generates a signing secret for that connection and shows it once. Copy it into your receiver's secret store straight away. If you lose it, disconnect the webhook and connect it again to get a new one.

Event types

• monitor.down: a monitor failed and an incident opened.
• monitor.up: the monitor recovered and the incident closed.
• ssl.expiring: a monitored certificate is approaching expiry.
• domain.expiring: a monitored domain registration is approaching expiry.
• maintenance.started: a maintenance window began.
• maintenance.ended: a maintenance window ended.

The Test button sends an event named test, so your receiver can accept it without treating it as a real incident. The event name is also sent in the X-SutramX-Event header.

Verify the signature

Every request carries X-SutramX-Timestamp (Unix seconds) and X-SutramX-Signature. The signature is "sha256=" followed by the hex HMAC-SHA256 of the timestamp, a dot, and the raw request body, keyed with your signing secret. Compute it over the raw bytes before parsing the JSON, compare in constant time, and reject timestamps older than about five minutes.

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: the request body exactly as received (string or Buffer)
function verifySutramX(rawBody, headers, secret) {
    const timestamp = headers['x-sutramx-timestamp'];
    const signature = headers['x-sutramx-signature'] || '';
    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

    const expected = 'sha256=' + createHmac('sha256', secret)
        .update(`${timestamp}.${rawBody}`)
        .digest('hex');
    const a = Buffer.from(signature);
    const b = Buffer.from(expected);
    return a.length === b.length && timingSafeEqual(a, b);
}

Each delivery has an X-SutramX-Delivery ID that stays the same on every retry. Store recent IDs and ignore repeats so a retried delivery is never processed twice.

Zapier

Also on Starter and above: to trigger a Zap, create one with the "Webhooks by Zapier → Catch Hook" trigger and connect its URL on the Zapier card in the same way.

Connect it in SutramX

1. Sign in to the SutramX dashboard and open Integrations & API in the sidebar, then the Integrations tab.
2. On the Webhooks card, click Connect. Where you see "Connect with …", you just sign in and approve. Otherwise the card shows two or three short steps and one box to paste into.
3. Already have a webhook link? Paste it into the box at the top of the page and SutramX works out which service it belongs to.
4. SutramX sends a test straight away so you can confirm delivery before any real incident.
5. Optional: use Routing to send only some monitors or groups to this channel.

You can connect more than one Webhooks destination. Each connection has its own routing, so different channels can receive different monitors.

Other incident and developer integrations

• Opsgenie alerts setup: Create and auto-close alerts with an API integration key.
• Email & team members alerts setup: Invite teammates, then choose exactly who receives alert emails.