Webhooks notify your tools when the governance state changes in a space. Use them to open tickets, send team chat messages or run pipeline steps when, for example, a risk level increases, an approval is requested or a review is created.
A webhook subscription is linked to a specific space. Saidot sends a delivery to your endpoint only when the events it subscribes to happen in that space. Only Admins can manage webhooks. Webhook endpoints are registered through the Saidot APIs, with the token of an Admin or of a service account.
Webhook delivery must be enabled for your organisation. Contact your Customer Success team if it isn't.
Event types
|
Event group |
Event types |
Example use |
|---|---|---|
|
Risk level |
|
Open a ticket for the team that owns the system |
|
Approvals |
|
Notify the approver in team chat, and close the ticket when the item is approved or the request is withdrawn |
|
Versions |
|
Start a re-evaluation in your release pipeline |
|
Lifecycle |
|
Unblock a deployment when the move to deployment is approved |
|
Monitoring |
|
Record in your ITSM tool that a system's context was confirmed |
|
Records created |
|
Add the review or the incident to your ITSM tool |
|
Observability |
|
Forward runtime events to the team on call |
|
Test |
|
Check that your endpoint receives deliveries |
Note that while approval requests, approvals and withdrawn requests send webhooks, rejected requests do not.
When subscribing to observability.event_received, the Fire webhook action of the Event-driven governance actions Workflow must be active for events linked to a system. See Observability events for more information on how the Workflow is configured.
Delivery format
A delivery is a JSON envelope with the event type, a timestamp, a version, the space ID and the event's data. The data depends on the event type. For example, for a risk level increase, it contains the system and its old and new risk level. The full payloads of the event types are in the Saidot API documentation at app.saidot.ai/api.
Subscribe and test an endpoint
-
List the event types.
GET /api/v1/space/{spaceId}/webhooks/eventsreturns the event types you can subscribe to, with their group and description. -
Register the endpoint.
POST /api/v1/space/{spaceId}/webhookswith your endpoint's HTTPS URL, the event types to subscribe to and a description. An empty list of event types subscribes the endpoint to all events in the space. -
Store the signing secret. The response contains the endpoint's signing secret. It is shown only at creation, so store it in your secret store straight away. Your endpoint uses it to verify deliveries.
-
Send a test ping.
POST /api/v1/space/{spaceId}/webhooks/{id}/testsends apingdelivery to your endpoint. The test ping isn't retried. If you receive a 400 response, webhook delivery isn't enabled for your organisation.
Subscribe each endpoint only to the events its tool uses, so the tool receives targeted information and isn't overloaded.
Verify a delivery
Saidot signs its deliveries following the Standard Webhooks specification. A delivery contains three headers: webhook-id, webhook-timestamp and webhook-signature. Verify every delivery before you act on it:
-
Decode the secret. The secret starts with
whsec_. Remove the prefix and base64-decode the rest to get the signing key. -
Recompute the signature. Compute the HMAC-SHA256 of the webhook ID, the timestamp and the raw request body, joined with full stops, and encode it in base64.
-
Compare the signatures. The
webhook-signatureheader contains one or more signatures, separated by spaces, each starting withv1,. Compare them with yours in constant time, and accept the delivery if one matches. -
Check the timestamp. Reject a delivery whose timestamp is more than five minutes from your own clock.
Standard Webhooks libraries exist for most languages and perform these checks for you.
Retries and duplicates
Saidot retries a delivery after a 5xx, 408 or 429 response, a timeout or a network error, with an increasing pause, up to five attempts. Other responses fail the delivery straight away.
A retry has the same webhook-id, with a new timestamp and signature. Record the webhook-id to recognise a delivery you have already processed to ensure a retry won’t create a duplicate ticket or message.
After five consecutive failed deliveries, Saidot disables the endpoint. Fix the endpoint, then re-enable it with POST /api/v1/space/{spaceId}/webhooks/{id}/enable. You can send a test ping to a disabled endpoint to check it before you re-enable it: the ping doesn't count towards its failed deliveries.
Maintain the endpoint
-
Delivery log:
GET /api/v1/space/{spaceId}/webhooks/{id}/deliverieslists the delivery attempts, with their event type, event ID, status, HTTP status, number of attempts, time of the last attempt and error message. -
Secret rotation:
POST /api/v1/space/{spaceId}/webhooks/{id}/rotate-secretissues a new secret. The old secret stops working immediately, and every later delivery is signed with the new one. Make your endpoint accept both secrets during the switch: a delivery your endpoint rejects with a 401 is not retried. -
Subscriptions: update the endpoint's event types when your teams change what they follow up on, and delete endpoints that are no longer used.
Signing secrets are credentials. Never share them in documents, chats or screenshots.