Webhooks

Webhooks are only available on Scale and Enterprise plans

IcePanel can notify your server in real time whenever model objects or model connections change in your organization. You register a subscription pointing to a public HTTPS endpoint, and IcePanel will POST a signed JSON payload to that URL for every matching event.

Subscriptions

A subscription tells IcePanel where to deliver events. All webhook subscriptions live under your organization settings. To create one, navigate to your organization settings, select Webhooks, then select Create webhook. Fill in the dialog , adding a custom name for your webhook so you can identify and add the endpoint URL.

Select Create webhook, and copy the signing secret displayed as it will not be shown again.

Events

When model object or connection data in your organization changes, IcePanel fires an event for each enabled subscription and sends a `POST` request with `Content-Type: application/json` to the endpoint configured on each subscription.

The request body looks like this:

{
  "collection": "model-object",
  "operation": "updated",
  "organizationId": "0JnNFdtmTTDTZbH0NLLR",
  "subscriptionId": "nzIKI2OkmMm1z3KcqHNl",
  "resourceId": "nzIKI2OkmMm1z3KcqHNl",
  "before": {
    "id": "0kaIAscJNGbY4zdwZUXp",
    "versionId": "OPMle3buwNOgEbXkCvBm",
    "landscapeId": "87OkRSC8YfyyUZswblF0"
  },
  "after": {
    "id": "0kaIAscJNGbY4zdwZUXp",
    "versionId": "OPMle3buwNOgEbXkCvBm",
    "landscapeId": "87OkRSC8YfyyUZswblF0"
  }
}

Consumers should consider that the before and after values will vary depending on the collection the operation was executed on, while the top-level fields are always present.

Each field in the payload is described below:

Field	Type	Description
collection	string	Check table bellow
operation	string	Check table bellow
organizationId	string	Organization the event belongs to
subscriptionId	string	Subscription that dispatched this event
resourceId	string	ID of the affected resource
before	object | null	State before the change. null for created events
after	object | null	State after the change. null for deleted events

Webhook consumers are encouraged to call back the IcePanel API to fetch the full, up-to-date state of the affected resource. The following table describes the collections and operations that are currently supported by IcePanel webhooks.

Collection	Operations	API reference
model object	created updated deleted	Get model object
model connection	created updated deleted	Get model connection

Signature Validation

Signature validation is a way to verify that an incoming HTTP request was genuinely sent by IcePanel and has not been tampered with in transit. IcePanel signs each request using a shared secret known only to IcePanel and the user who created the webhook subscription.

Each incoming webhook request sent by IcePanel includes headers that should be used to perform signature validation:

• X-IcePanel-Signature— an HMAC-SHA256 hex digest

• X-IcePanel-Timestamp — a Unix timestamp in seconds

To verify the received webhook request, check the X-IcePanel-Timestamp header and reject requests older than 5 minutes to prevent replay attacks. Then recompute the HMAC-SHA256 signature using the received timestamp, body and your subscription secret. Compare the recomputed signature against the received X-IcePanel-Signature header value. Both should be equal for the signature validation to pass.

Below is an example of how to verify using Node.js:

// Shared secret from the IcePanel webhook subscription, used to verify request authenticity
const WEBHOOK_SUBSCRIPTION_SECRET = process.env.WEBHOOK_SUBSCRIPTION_SECRET

// Requests with a timestamp outside this window are rejected to prevent replay attacks
const WEBHOOK_TIMESTAMP_TOLERANCE = process.env.WEBHOOK_TIMESTAMP_TOLERANCE

/**
 * Validates an incoming webhook request by verifying the HMAC-SHA256 signature
 * @param {{ timestamp: string, body: string, signature: string }} options
 * @returns {boolean}
 */
function validateSignature(options) {
  // Reject requests older than WEBHOOK_TIMESTAMP_TOLERANCE
  const requestTimeMs = parseInt(options.timestamp, 10) * 1000
  if (Math.abs(Date.now() - requestTimeMs) > WEBHOOK_TIMESTAMP_TOLERANCE) {
    return false
  }

  // Compute the HMAC-SHA256 signature
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SUBSCRIPTION_SECRET)
    // Interpolate timestamp and body using a dot character
    .update(`${options.timestamp}.${options.body}`)
    .digest('hex')

  // Compare the received signature with the computed signature
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(options.signature)
  )
}

Disabling webhooks

IcePanel allows you to disable webhooks that have been created. This means that if you wish to stop receiving events to a particular endpoint temporarily, you can disable the active webhook for as long as desired, then re-enable it when ready. This prevents you needing to completely delete the webhook, and is designed to give you greater control.

To disable a webhook, select the ellipsis button that appears when you hover over a webhook. Here you can select “Disable webhook”. To re-enable it follow the same steps, but instead select the updated button “Enable webhook”.