Webhook

Webhook notifications send a JSON payload to an HTTPS endpoint of your choice when a guardrail violation occurs. See the Notifications overview for how channels fit into the guardrails system.

Configuration

URL (required) — The HTTPS endpoint that will receive the webhook POST request
Signing Secret (optional) — A secret used to generate an HMAC-SHA256 signature for payload verification

Example Payload

When a change freeze window or deployment policy is violated, OpsTrails sends a POST request with the following JSON body:

json

{
  "type": "guardrail.violation",
  "guardrailType": "change-freeze",
  "guardrailName": "Holiday Freeze 2026",
  "violation": {
    "eventType": "deployment",
    "source": "//github.com/acme/api",
    "subject": "production",
    "version": "v2.4.1",
    "timestamp": "2026-12-25T14:30:00Z"
  },
  "organization": {
    "id": "org_abc123",
    "name": "Acme Corp"
  },
  "timestamp": "2026-12-25T14:30:05Z"
}

Signature Verification

If you provide a signing secret, OpsTrails includes an X-OpsTrails-Signature header containing an HMAC-SHA256 hex digest of the request body. Use this to verify that the request came from OpsTrails.

javascript

const crypto = require("crypto");

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
const signature = req.headers["x-opstrails-signature"];
const isValid = verifySignature(req.body, signature, SIGNING_SECRET);

✅ Tip

Always verify the signature in production to ensure webhook payloads are authentic. Use a timing-safe comparison to prevent timing attacks.

💡 Info

The number of webhook channels you can create depends on your plan. See Limits & Quotas for details.

Previous← Email NextPagerDuty →