# 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 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:

![](/files/-MEIRBX4lfHIB5bFF9hF)

{% hint style="info" %}
You can set up as many webhooks for a Stack as you need, though each one *must* have a unique endpoint.
{% endhint %}

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](/spacelift/integrations/webhooks.md#validating-payload) that the incoming requests are indeed coming from Spacelift:

![](/files/-MEIRwEGzdGMxaRzdINR)

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:

![](/files/-MEISM4cJTVF2MXSHl_b)

{% hint style="info" %}
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.
{% endhint %}

### 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:

![](/files/-MEIUt0njB-7vAAaiznC)

...and click on the Enabled toggle to see it going *gray*:

![](/files/-MEIV3KSHOWnpxNyRH5a)

Reversing this action is equally simple - just follow the same steps making sure that the toggle goes *green*:

![](/files/-MEIVEnnQFQHHEHKNxIt)

### Interpreting webhook payload

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

```javascript
{
    "account": "spacelift-io",
    "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": "",
        "labels": []
    }
}
```

The payload consists of a few fields:

* `account` is the name (subdomain) of the account generating the webhook - useful in case you're pointing webhooks from various accounts at the same endpoint; 
* `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](/spacelift/concepts/stack.md) 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 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 [this article](https://medium.com/@vampiire/how-to-verify-the-authenticity-of-a-github-apps-webhook-payload-8d63ccc81a24) for details.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://spacelift-io.gitbook.io/spacelift/integrations/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.