Apply for invite to IaCP

Webhooks

Overview

Webhooks are very simple, yet very powerful way to integrate with external systems such as Slack, email, or any other system you may want to integrate with via an HTTP post. The webhook, a simple application designed to handle incoming HTTP requests, will parse and process a payload from Scalr then integrate with the external services of your choosing when events occur on your 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 the environment scope. 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:

../_images/endpoint.png

A secret key will be generated for you. This key should be used in your webhook code to verify that Scalr is the source of the payload.

Webhook Configuration

The webhook configuration is where you will choose the endpoint and which events will trigger a webhook call. A webhook can be created at the environment or workspace scope.

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

Once you are on the webhook page, you can configure it with the following settings:

../_images/webhook.png

After you create a Terraform run and one of the events are triggered, you will see the payload sent to the webhook.

Deliveries

All webhook events will be logged under the deliveries. If you have access to the full environment you can find all deliveries for the environment under the integrations tab. If you only have access to your workspace, you can find the deliveries per workspace in the deliveries tab:

../_images/deliveries.png

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

{
 "environment":{
    "id":"org-sscctukpakjtb0g",
    "name":"ApplicationA(vcs)",
    "url":"https://your.scalr.server/#/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://your.scalr.server/#/workspaces/runs/dashboard?runId=run-svuin1c074sdku6"
 },
 "variables":{

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