ChangeVault Docs

Outgoing webhooks let ChangeVault push events to any external system in real time — incident management tools, custom dashboards, chat bots and more.

See Notifications → Outgoing webhooks for setup instructions.

Payload format

Every delivery is a POST request with a JSON body:

{
  "event": "change.created",
  "timestamp": "2025-04-07T10:00:00.000Z",
  "data": {
    "id": "uuid",
    "title": "Deployed api-service v3.1.0",
    "risk_level": "medium",
    "status": "completed",
    "organization_id": "org_...",
    "service": { "id": "uuid", "name": "api-service" },
    "host_ref": { "id": "uuid", "hostname": "web-01" },
    "tags": ["deploy", "prod"],
    "created_at": "2025-04-07T10:00:00Z"
  }
}

Events

Event	Trigger
`change.created`	A new change is logged
`change.updated`	An existing change is updated
`change.deleted`	A change is deleted

Request headers

Header	Description
`Content-Type`	`application/json`
`X-ChangeVault-Event`	The event name (e.g. `change.created`)
`X-ChangeVault-Timestamp`	Unix timestamp in milliseconds
`X-ChangeVault-Signature`	HMAC-SHA256 signature (see below)

Verifying signatures

Each delivery is signed with your webhook's secret using HMAC-SHA256. Verify the signature to confirm the request came from ChangeVault.

The signed payload is: {timestamp}.{raw JSON body}

import crypto from "crypto";

function verifySignature(
  secret: string,
  rawBody: string,
  timestamp: string,
  signature: string
): boolean {
  const payload = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Always verify the signature before processing a webhook. Reject requests with invalid or missing signatures.

Retries

ChangeVault does not automatically retry failed deliveries. Use the Test button in the dashboard to re-send a test payload at any time.

Timeouts

Deliveries time out after 10 seconds. Ensure your endpoint responds quickly — offload heavy processing to a background job.