Webhooks

Spacelift can optionally be set to send webhooks - POST requests about run state changes - to an HTTP endpoint of your choice.

Setting up webhooks

Webhooks can be set up by Spacelit 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 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:

Enabling and disabling webhooks

By default webhooks are enabled which means that they are triggered every time there's a run state change event on the Stack they're 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:

Intepreting webhook payload

Here's an example webhook payload for a notification about a manually triggered run having finished:

{
    "state": "FINISHED",
    "stateVersion": 4,
    "timestamp": 1596979684,
    "run": {
        "id": "01EF9PFPNFFM2MQXTJKHK1B869",
        "branch": "master",
        "commit": {
            "authorLogin": "marcinwyszynski",
            "authorName": "Marcin Wyszynski",
            "hash": "0ee3a3b7266daf5a1d44a193a0f48ce995fa75eb",
            "message": "Update demo.tf",
            "timestamp": 1596705932,
            "url": "https://github.com/spacelift-io/demo/commit/0ee3a3b7266daf5a1d44a193a0f48ce995fa75eb"
        },
        "createdAt": 1596979665,
        "delta": {
            "added": 0,
            "changed": 0,
            "deleted": 0,
            "resources": 1
        },
        "triggeredBy": "marcinw@spacelift.io",
        "type": "TRACKED"
    },
    "stack": {
        "id": "spacelift-demo",
        "name": "Spacelift demo",
        "description": ""
    }
}

The payload consists of a few fields:

• state is a string representation of the run state at the time of the notification being triggered;

• stateVersion is 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;

• timestamp is the unix timestamp of the state transition;

• run contains information about the run, its associated commit and delta (if any);

• stack contains some basic information about the parent Stack of the run;

Validating payload

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 a X-Signature header generated from the combination of the secret and payload. Since we're using the exact same mechanism as GitHub to generate signatures, please refer to their documentation on securing webhooks. Many language-specific GitHub SDKs will offer that functionality, too, though when using these please note that we're putting the signature at a different header than GitHub.