Enabling System Webhooks

System webhooks let System editors have the platform call an HTTPS endpoint, or trigger a GitLab pipeline, when a commit is recorded or a change request is opened. They are off by default. This page covers what to configure on the registry service. What users see is in Webhooks; the request format and API are in the Webhook reference.

Prerequisites

• Eventing. Webhooks ride on the same NATS eventing that powers Notifications: nats.enabled: true in your Helm values, and FILE_SERVICE_NATS_TOKEN plus FILE_SERVICE_FEATURE_FLAGS__EVENTING_ENABLED: "true" in the istari-fileservice secret, as set up in Istari Digital Platform installation and its NATS Secret. The registry refuses to start when webhooks are enabled but eventing or NATS is not configured.
• Outbound HTTPS from the registry pods to the endpoints your users will target. See Network requirements.

Registry service

Add these keys to the istari-fileservice secret, or set them as fileservice.env entries in your values file as in Scenario 7:

istari-fileservice-secret.yaml (additions)

  FILE_SERVICE_FEATURE_FLAGS__WEBHOOKS_ENABLED: "true"
  FILE_SERVICE_WEBHOOK_MASTER_SECRET: "<webhook_master_secret>"
  FILE_SERVICE_ISTARI_INSTANCE_URL: "https://<customer_istari_fqdn>"

Variable	Purpose
FILE_SERVICE_FEATURE_FLAGS__WEBHOOKS_ENABLED	Mounts the webhook API and starts the delivery workers. Requires FILE_SERVICE_FEATURE_FLAGS__EVENTING_ENABLED: "true" and NATS.
FILE_SERVICE_WEBHOOK_MASTER_SECRET	Encrypts webhook signing secrets and credentials (GitLab trigger tokens) at rest. Generate a random value of at least 32 characters. Set it before the first webhook is created and never change it afterwards. Changing it makes every existing webhook's secret and token undecryptable, and those webhooks stop delivering until they are deleted and recreated. If it is left unset, the registry falls back to a publicly known default and logs a warning at startup.
FILE_SERVICE_ISTARI_INSTANCE_URL	The public URL of the web app (the same value as the frontend's VITE_UI_URL). It appears in every payload as istari_instance and is used to build the deep_link fields. If unset, payloads carry http://localhost:8000.

Apply the secret, then restart the registry deployment (a Helm upgrade or a rollout restart).

caution

Treat FILE_SERVICE_WEBHOOK_MASTER_SECRET like a database password: back it up with your other secrets and carry it across upgrades unchanged.

Frontend

No frontend configuration is needed. The Webhooks tab is under Settings on the redesigned System page, which is on by default. A user who has turned System redesign off under Settings → Application → Experimental Features must turn it back on to see the tab. To stop users turning it off, list system-redesign in the frontend's VITE_EXPERIMENTAL_LOCKED; the row then shows Managed by your deployment.

Webhooks can also be managed from the REST API or Python client.

Network requirements

Deliveries are outbound HTTPS requests from the registry pods to the endpoints your users configure: an internal service, an automation platform, or a GitLab instance. Egress rules and proxies must allow that traffic.

The registry applies these rules to every target, when a webhook is saved and again each time it connects:

• The URL must use https://, and the receiver must present a certificate the registry trusts.
• The host must resolve to a publicly routable IP address. Private (RFC 1918), loopback, link-local, and other non-global ranges are rejected, so a receiver on a private address must be reached through a publicly routable HTTPS endpoint.
• Redirects are not followed.

Each delivery attempt times out after 10 seconds. Failed attempts are retried after 30 s, 2 min, 10 min, and 1 h, then dead-lettered.

Verify

1. The registry's startup log should not contain FILE_SERVICE_WEBHOOK_MASTER_SECRET is unset/default.
2. As a user with Editor access to a System, GET /api/v2/systems/{system_id}/webhooks returns 200 with an empty page. A 404 means the flag is not active on the running pods.
3. In the web app, open a System, click Settings, and confirm the Webhooks tab offers + Webhook rather than Webhooks aren't enabled on this deployment.

Data retention

Delivery records are kept for 30 days and purged nightly. Deleting a webhook removes its delivery records immediately.