Webhooks¶

Reading time: 2-3 minutes

Overview¶

Webhooks are very simple, yet very powerful way to integrate with external systems such as Slack, email, or any other system via an HTTP post request. The webhook, a simple application designed to handle incoming HTTP requests, will parse and process a payload from Scalr then integrate with the external systems when events occur during a Terraform run, such as:

Run complete - When the run is completed successfully
Run errored - When the run is prevented from continuing due to an error in the code, cancellation, or a policy failure.
Run needs attention - When someone will need to review a plan based on the workspace not having auto-approval or if a policy is override is required.

During any of these events Scalr will send a payload to an endpoint that the the administrator or workspace owner has defined.

Endpoint Configuration¶

Endpoints can be configured at in environments. An endpoint is required as it is the URL that Scalr will send the payload to. To create an endpoint, click on integrations and then endpoints on the main toolbar. Enter the required information:

A secret key is generated. This key must be used in the webhook code to verify that Scalr is the source of the payload.

Webhook Configuration¶

The webhook configuration is where the endpoint and trigger events are defined. Webhooks can be created at the environments or in workspaces.

To create a webhook at the environment level, click on integrations and then webhooks. If a webhook is created in an environment then all workspaces within that environment will inherit it. To create a webhook at in a workspace, go to the main dashboard of that workspace, click on webhooks, and then new webhook.

On the webhook page configure it with the following settings:

After a Terraform run has triggered one of the events the payload that was sent to the webhook can be viewed.

Deliveries¶

All webhook events will be logged under the deliveries. These can be seen via Integrations in the environment or in the workspace deliveries tab:

Each delivery will also show the payload that was sent for that event:

{
 "environment":{
    "id":"org-sscctukpakjtb0g",
    "name":"ApplicationA(vcs)",
    "url":"https://my-account.scalr.io/#/13456/17931/dashboard"
 },
 "event_name":"run:needs_attention",
 "payload_version":1,
 "run":{
    "created_at":"2020-07-08T13:44:53",
    "created_by":{
       "email":"user@scalr.com",
       "id":"user-stp8qjepev3a598",
       "username":"user123"
    },
    "id":"run-svuin1c074shte0",
    "message":"Updated instance\n",
    "source":"ui",
    "status":"policy_override",
    "updated_at":"2020-07-08T13:45:13",
    "url":"https://my-account.scalr.io/#/workspaces/runs/dashboard?runId=run-svuin1c074sdku6"
 },
 "variables":{

 },
 "webhook":{
    "id":"wh-svuidnaehdgvl60",
    "name":"MyWebhook"
 },
 "workspace":{
   "id":"ws-sse6a0avr9qji18",
    "name":"Staging",
    "url":"https://my-account.scalr.io/#/workspaces/dashboard?workspaceId=ws-sse6a0avr9qks93"
 }
}