Webhooks

Webhooks push a notification to a service you run whenever something happens in a System. Configure a webhook once, and the platform sends an HTTPS request to your endpoint, or starts a GitLab pipeline, every time a subscribed event occurs: a new commit, or a change request being opened. Use them to re-run an analysis, update a PLM or issue tracker, or ping a team channel without polling the platform.

Availability

Webhooks appear only when your IT administrator has enabled them for the deployment. If the Webhooks tab reads Webhooks aren't enabled on this deployment, ask your administrator; see Enabling System Webhooks.

Webhooks are managed under Settings → Webhooks on the redesigned System page, which is on by default. If you turned System redesign off under Settings → Application → Experimental Features, turn it back on; see Application Settings.

How webhooks work

A webhook pairs the events you subscribe to with one target, the place the platform sends each event:

• HTTP: you run a service that receives a signed JSON POST. Use it for your own app, an automation platform, or a chat or ticketing integration.
• GitLab Pipeline: the platform starts a pipeline in a GitLab project and passes the event in as CI/CD variables. Use it when the work you want to run already lives in GitLab CI: there is no receiver to host and no signature to verify. GitLab's pipeline trigger API expects its own token and branch, so pointing an HTTP webhook at GitLab does not work.

Before you start

Role on the System	What you can do
Editor or above	Add, edit, enable, disable, and delete webhooks; view deliveries
Viewer	See each webhook's settings (read-only) and its recent deliveries

Each System can have up to 10 webhooks. Webhooks belong to the System, not to the person who created them: any Editor can change or delete them.

Events

A webhook subscribes to one or both events. Switch them on individually when you set up the webhook.

Event in the web app	Fires when	Event type in the payload
New Commit	A commit is recorded on any branch of the System, for example when you Edit files and Save	system.snapshot.created
Create New Change Request (Open)	A change request is opened in the System. Reopening a closed change request does not fire the event again	system.change_request.opened

Events fire for changes made in the web app, from the Python client, or by an integration: anything that records a commit or opens a change request.

The New Commit payload does not name the branch the commit was recorded on, so a receiver cannot filter commits by branch. Create New Change Request (Open) names both the source and target branches.

Targets

Target	What the platform sends	You need
HTTP	A signed POST with a JSON body describing the event, to a URL you provide	An HTTPS endpoint reachable from the platform (see Reachability)
GitLab Pipeline	A pipeline trigger on a GitLab project, with the event passed to the pipeline as CI/CD variables	A GitLab project with a pipeline trigger token, on a GitLab instance reachable from the platform (see Reachability)

The target type is fixed when you create a webhook. To switch a webhook from HTTP to GitLab Pipeline (or back), delete it and create a new one.

Open the Webhooks tab

1. Open the System.
2. Click Settings in the System header.
3. Click the Webhooks tab. Existing webhooks are listed on the left; the selected webhook's Setup form and Recent Deliveries are on the right.

Add an HTTP webhook

Requires Editor or above.

1. On the Webhooks tab, click + Webhook.
2. Enter a Title. This is how the webhook appears in the list.
3. Leave Target as HTTP.
4. Enter the Payload URL. It must start with https:// and be reachable from the platform (see Reachability).
5. Leave Credential empty. It is stored encrypted but is not sent with deliveries in this release; the signing secret authenticates each request instead.
6. Under System Events, switch on the events to subscribe to. At least one is required.
7. Click Save.
8. The Webhook created dialog shows the webhook's signing secret (whsec_…). Copy it now. It is shown once and cannot be retrieved later. Configure your endpoint with it so it can verify that each request really came from your platform (see Verify the signature). Click I've copied the secret to close the dialog.

The new webhook is enabled immediately.

Add a GitLab Pipeline webhook

Requires Editor or above.

Before you start, in GitLab:

• Make sure the GitLab instance is reachable from the platform. A GitLab instance on a private network is rejected; see Reachability.
• Make sure the project has a .gitlab-ci.yml on the branch or tag you will enter as Ref. Each event runs that file's pipeline, so use rules: to choose which jobs run for which event. See GitLab Pipeline targets for an example.
• Open the project's Settings → CI/CD → Pipeline trigger tokens, add a trigger token, and copy it. Adding a trigger token requires the Maintainer role on the project.

Then, in the web app:

1. On the Webhooks tab, click + Webhook.
2. Enter a Title.
3. Set Target to GitLab Pipeline.
4. Enter the GitLab URL: the base URL of your GitLab instance, such as https://gitlab.example.com. Do not include a project path or an /api/... path.
5. Enter the Project: the numeric project ID, or the full path such as group/project.
6. Enter the Ref: the branch or tag the pipeline should run on.
7. Paste the Pipeline trigger token. It is required and is stored encrypted; after saving, only its last four characters are shown.
8. Switch on the System Events to subscribe to.
9. Click Save.

GitLab Pipeline webhooks have no signing secret; the trigger token is the credential. Your pipeline receives the event as the CI/CD variables ISTARI_EVENT_TYPE, ISTARI_DELIVERY_ID, and ISTARI_PAYLOAD.

Enable or disable a webhook

Use the switch next to a webhook in the list. A disabled webhook keeps its settings but receives no events, and events that occur while it is disabled are not delivered later.

A webhook is also disabled automatically when its endpoint answers 410 Gone (see Delivery statuses).

Edit a webhook

Requires Editor or above.

1. Select the webhook in the list. Its Setup form opens.
2. Change the Title, the target details, the credential, or the System Events.
3. Click Save. Cancel discards unsaved changes.

Notes:

• The Target type cannot be changed after creation.
• HTTP: Remove credential clears a stored credential; entering a new value replaces it.
• GitLab Pipeline: the trigger token can be replaced but not removed. Changing the GitLab URL or Project requires entering the trigger token again in the same save, so a stored token is never sent to a destination it was not entered for.
• The signing secret of an HTTP webhook cannot be rotated. If it is lost or exposed, delete the webhook and create a new one.

Delete a webhook

Requires Editor or above.

1. Select the webhook and click Delete Webhook at the bottom of the Setup form.
2. Confirm in the Delete webhook dialog.

The webhook stops receiving events immediately and its delivery history is removed. This cannot be undone.

Recent Deliveries

Select a webhook and open the Recent Deliveries tab to see its 50 most recent deliveries. Click Refresh to update the list. Each row shows:

Column	Meaning
Event	Which event was delivered
Status	See Delivery statuses
Attempts	How many times the platform has tried to deliver it
Response	The HTTP status your endpoint (or GitLab) returned, and the start of its response body. Hover over the message to read it in full
Triggered	When the event occurred
Next attempt	For a failed delivery, when it will be retried

Deliveries are asynchronous: expect the first attempt within about 30 seconds of the event. Delivery history is kept for 30 days.

Delivery statuses

Status	Meaning
Pending	Queued and about to be attempted
Delivered	Your endpoint returned a 2xx response (GitLab returns 201 when the pipeline is created)
Failed	The attempt failed; it will be retried at the time shown in Next attempt
Dead letter	All retries failed; the platform has given up on this delivery
Disabled (410)	Your endpoint returned 410 Gone, so the webhook was disabled. Re-enable it once the endpoint is available again

A failed delivery is retried after 30 seconds, 2 minutes, 10 minutes, and 1 hour (five attempts in total). Any response other than 2xx, or no response within 10 seconds, counts as a failure. Redirects are not followed.

Reachability

The platform makes the request from the registry service, so the target must be reachable from where the platform runs:

• The URL must use https://, with a certificate the registry trusts.
• The host must resolve to a publicly routable address. Private, loopback, and link-local addresses are rejected when you save the webhook and again at delivery time.

If your receiver sits on a private network, put it behind a publicly routable HTTPS endpoint, or ask your IT administrator about the deployment's webhook settings.

Troubleshooting

Symptom	Likely cause
The Webhooks tab says webhooks aren't enabled on this deployment	The registry's webhooks feature is off. Ask your IT administrator; see Enabling System Webhooks
There is no Settings button or Webhooks tab	You are on the legacy System page. Turn on System redesign under Settings → Application
Saving fails with a message about the URL or host	The URL is not https://, or the host does not resolve to a public address. See Reachability
Saving a GitLab webhook fails with a message about the GitLab URL	Enter the instance base URL only: no /api/v4/... path, query, or fragment
GitLab deliveries fail with 404	The trigger token or project is wrong (GitLab reports an invalid token as a 404)
GitLab deliveries fail with 400	The Ref does not exist in the project
Deliveries show Dead letter	The endpoint was unreachable or kept returning errors for over an hour. Fix the endpoint; past events are not redelivered
Deliveries show Delivered but nothing happened on your side	Your endpoint accepted the request. Check its logs, and make sure it verifies the signature rather than rejecting requests outright

For the request headers, payload fields, signature verification, GitLab CI/CD variables, and the REST API, see the Webhook reference.