Spacelift can be configured to send webhook notifications for various events to an HTTP endpoint of your choice.
Setting up webhooks»
Webhooks can be set up by Spacelift administrators. They can be easily created or modified in the
Navigate to the webhooks section»
Fill required fields»
Secret parameter is optional and is used to validate the received payload.
You can learn more about it in the validating payload section.
Reference webhooks in policy rules»
Webhook messages are delivered using the notification policy.
When defining rules, the policy expects you to reference the webhook by its
ID which you
can copy from the webhook list view:
Webhook deliveries and their response statuses are stored and can be explored by selecting a specific webhook and viewing its details. You'll be presented with a list of deliveries, their status codes and when they happened. You can also click on each delivery to view more details about it:
Default webhook payloads»
The following section documents the default webhook payloads sent for each event type. However, if required, webhook payloads can be customized via a notification policy.
Here's an example of the default webhook payload for a notification about a finished tracked run:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
The payload consists of a few fields:
accountis the name (subdomain) of the account generating the webhook - useful in case you're pointing webhooks from various accounts at the same endpoint;
stateis a string representation of the run state at the time of the notification being triggered;
stateVersionis the ordinal number of the state, which can be used to ensure that notifications that may be sent or received out-of-order are correctly processed;
timestampis the unix timestamp of the state transition;
runcontains information about the run, its associated commit and delta (if any);
stackcontains some basic information about the parent Stack of the
Internal error events»
1 2 3 4 5 6 7
Internal errors will always have the same fields set and some of them will be static for an event:
titleis the title (summary) of the error.
bodyis the is the full explanation of what went wrong.
erroris a description of the error that happened.
severitycan be one of three different constants:
accountis the account for which the error happened.
In order to validate the incoming payload, you will need to have the secret handy - the one you've generated yourself when creating or updating the webhook.
Every webhook payload comes with two signature headers generated from the combination of the secret and payload.
X-Signature header contains the SHA1 hash of the payload, while
X-Signature-256 contains the SHA256 hash. We're using the exact same mechanism as GitHub to generate signatures, please refer to GitHub docs for details.
Attaching webhooks to stacks»
We recommend that you use notification policies to route stack events to your webhooks. Stack webhook integrations are provided for backwards compatibility.
Webhooks can be set up by Spacelift administrators on per-stack basis. In order to do that, navigate to the Integrations section of the stack settings view. From the list of available integrations, select the Add webhook option:
You can set up as many webhooks for a Stack as you need, though each one must have a unique endpoint.
You will be presented with a simple setup form that requires you to provide and endpoint to which the payload is sent, and an optional secret that you can use to validate that the incoming requests are indeed coming from Spacelift:
Please note that it's up to you to come up with a reasonably non-obvious secret.
Once saved, the webhook will appear on the list of integrations:
Unlike some other secrets in Spacelift, the webhook secret can be viewed by anyone with read access to the stack. If you suspect foul play, consider regenerating your secret.
By default webhooks are enabled which means that they are triggered every time there's a run state change event on the Stack they are attached to. If you want to temporarily disable some of the endpoints, you can do that without having to delete the whole integration.
To do that, just click on the Edit button on the desired webhook integration section:
...and click on the Enabled toggle to see it going gray:
Reversing this action is equally simple - just follow the same steps making sure that the toggle goes green: