Overview

Outbound webhooks POST event notifications (for example when a test run completes, or when someone is @mentioned in a comment) to a URL you control. Each payload is signed with the subscription's secret so your receiver can verify it came from Shift-Left Studio. This guide walks the Outbound Webhooks settings screen exactly as it appears in the app. Explore the capability at webhooks.

Availability: Professional and Enterprise.

Before you begin

Webhooks are administrator-only. You need the manage_webhooks permission; without it the screen is not available to you.
Webhooks live under Settings → Integrations → Webhooks. The screen header reads Outbound Webhooks with the subtitle "Send signed event notifications to external systems."
Your Payload URL must be a public http(s) endpoint the engine can reach. URLs are validated to block server-side request forgery (SSRF), so internal or disallowed hosts are rejected.

Step 1 — Enable outbound webhooks

At the top of the screen, find the Enable Outbound Webhooks card. It carries a switch on the right.
When webhooks are off, the card reads "Turn on to send signed event notifications to external systems." and the panel below shows "Outbound webhooks are currently disabled. Use the switch above to enable them, then create a subscription."
Click the switch. On success you'll see the toast "Outbound webhooks enabled", the description changes to "Outbound webhooks are active. Create and manage subscriptions below.", and the Create webhook form and subscription list appear.
Flipping the switch off shows "Outbound webhooks disabled" and hides the management UI. This master toggle is stored in system settings, so you don't need to edit any environment variable.

Step 2 — Create a webhook

In the Create webhook form, fill in these fields and click Create:

Field	What it does
Payload URL	The `https://…` endpoint that receives the POST. Placeholder: `https://example.com/webhooks/shiftleft`. Required. Must start with `http://` or `https://`; disallowed/unreachable hosts are rejected with URL_NOT_ALLOWED.
Events	Which event types to subscribe to. Enter `*` (the default) for every event, or a comma-separated list such as `test.run.completed`.
Project ID (optional)	Scope the subscription to one project. Placeholder: `all projects`. Leave blank to receive events from every project.

The Create button is disabled until Payload URL has a value; while submitting it reads Creating…. On success you'll see the toast "Webhook created" and the new subscription appears in the list.

Step 3 — Copy the signing secret (shown once)

As soon as the webhook is created, an orange Copy your signing secret now banner appears with your secret (a value beginning whsec_). The banner warns: "This secret is shown only once and cannot be retrieved later. Store it securely."

Click Copy to copy the secret (the button briefly reads Copied).
Store it in your secret manager or receiver configuration.
Click Dismiss to close the banner.

If you navigate away without copying it, the secret is gone — you must Rotate (Step 4) to get a new one.

Step 4 — Manage a subscription

Each subscription row shows the Payload URL, an Enabled/Disabled badge, its subscribed event tags, and either the project ID or "All projects" plus the created timestamp. The row's action buttons are:

Control	What it does
Disable / Enable	Pauses or resumes deliveries. The label reflects the current state; toasts read "Webhook disabled" / "Webhook enabled."
Test	Fires a synthetic `webhook.test` event (payload "Test event from Shift-Left Studio") to the Payload URL. Toast: "Test event fired." Use it to confirm your receiver is reachable and your signature check works.
Deliveries	Expands an inline log of recent attempts (see Step 5).
Rotate	Generates a new signing secret. The old secret stops working immediately. The new secret is shown once in the same orange banner as Step 3 — copy it right away. Toast: "Signing secret rotated."
Trash icon	Deletes the subscription. You're asked to confirm "Delete webhook for [url]? This cannot be undone." Toast: "Webhook deleted."

Step 5 — Read the deliveries log

Click Deliveries on a subscription to expand its recent delivery attempts (most recent first). Each entry shows:

A green check (delivered) or red X (failed).
The event name and the attempt number.
The HTTP status code the receiver returned, an error message if the attempt failed, and the delivery timestamp.

If there are none yet you'll see "No deliveries yet." Fire a Test event or trigger a real event to populate it.

Step 6 — Verify the signature on your receiver

Every payload is signed with the subscription's secret. On your server, recompute the signature from the raw request body using your stored whsec_… secret and compare it to the signature header before trusting the payload. Reject any request whose signature doesn't match. Rotate the secret (Step 4) if you suspect it has leaked, and update your receiver with the new value.

Troubleshooting / Notes

URL rejected on create (URL_NOT_ALLOWED / INVALID_URL) — the Payload URL isn't a valid public http(s) URL, or it points at a disallowed host (SSRF protection). Use a reachable public HTTPS endpoint.
Screen shows only the disabled notice — outbound webhooks are turned off. Use the Enable Outbound Webhooks switch (Step 1).
Deliveries failing — check the status code and error in the Deliveries log; confirm your endpoint returns a 2xx and that your signature check accepts the current secret.
Lost the secret — it's shown only once; use Rotate to issue a new one, then update your receiver.
Webhooks are also a notification channel for dashboard alerts and surface comment @mentions.

Webhooks