Notification policies can be used to filter, route and adjust the body of notification messages sent by Spacelift. The policy works at the Space level meaning that it does not need to be attached to a specific stack, but rather is always evaluated if the Space it's in can be accessed by whatever action is being evaluated. It's also important to note that all notifications go through the policy evaluation. This means any of them can be redirected to the routes defined in the policy.
A notification policy can define the following rules:
- inbox - allows messages to be routed to the Spacelift notification inbox;
- slack - allows messages to be routed to a given slack channel;
- webhook - allows messages to be routed to a given webhook;
If no rules match no action is taken.
This is the schema of the data input that each policy request can receive:
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 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
The final JSON object received as input will depend on the type of notification being sent. Event-dependent objects will only be present when those events happen. The best way to see what input your Notification policy received is to enable sampling and check the Policy Workbench, but you can also use the table below as a reference:
||Internal error occurred|
||Module version updated|
Policy in practice»
Using the notification policy, you can completely re-write notifications or control where and when they are sent. Let's look into how the policy works for each of the defined routes.
Choosing a Space for your policy»
When creating notification policies you should take into account the Space in which you're creating them. Generally the policy follows the same conventions as any other Spacelift component, with a few small caveats.
Determining Space for run update notifications»
Run update messages will rely on the Space that the run is happening in. It will check any policies in that Space including policies inherited from other Spaces.
Determining Space for internal errors»
Most internal errors will check for notification policies inside of the root Space. However if the policy is reporting about a component that belongs to a certain Space and it can determine to which one it is, then it will check for policies in that or any inherited Space. Here is a list of components it will check in order:
- Worker pool
- AWS integration
If you are new to spaces, consider further exploring our documentation about them here
Inbox notifications are what you receive in your Spacelift notification inbox. By default, these are errors that happened during some kind of action execution inside Spacelift and are always sent even if you do not have a policy created. However using the policy allows you to alter the body of those errors to add additional context, or even more importantly it allows you to create your own unique notifications.
The inbox rule accepts multiple configurable parameters:
title- a custom title for the message (Optional)
body- a custom message body (Optional)
severity- the severity level for the message (Optional)
Creating new inbox notifications»
For example here is a inbox rule which will send
INFO level notification messages to your inbox
when a tracked run has finished:
1 2 3 4 5 6 7 8 9 10 11 12
Slack messages can also be controlled using the notification policy, but before creating any policies that interact with Slack you will need to add the slack integration to your Spacelift account.
The documentation section about Slack includes additional information like: available actions, slack access policies and more. Consider exploring that part of documentation first.
Another important point to mention is that the rules for Slack require a
channel_id to be defined. This can be found at the bottom of a channel's About section in Slack:
Now you should be ready to define rules for routing Slack messages. Slack rules allow you to make the same filtering decisions as any other rule in the policy. They also allow you to edit the message bodies themselves in order to create custom messages.
The Slack rules accept multiple configurable parameters:
channel_id- the Slack channel to which the message will be delivered (Required)
message- a custom message to be sent (Optional)
Filtering and routing messages»
For example if you wanted to receive only finished runs on a specific Slack channel you would define a rule like this:
1 2 3 4 5 6 7 8
Changing the message body»
Together with filtering and routing messages you can also alter the message body itself, here is an example for sending a custom message where a run which tries to attach a policy requires confirmation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14
This section of documentation requires you have configured at least one Named Webhook. Consider exploring that part of documentation first.
Webhook notifications are a very powerful part of the notification policy. Using them, one is able to not only receive webhooks on specific events that happen in Spacelift, but also craft unique requests to be consumed by some third-party.
The notification policy relies on named webhooks which can be created and managed in the Webhooks section of Spacelift. Any policy evaluation will always receive a list of possible webhooks together with their labels as input. The data received in the policy input should be used to determine which webhook will be used when sending the request.
The webhook policy accepts multiple configurable parameters:
endpoint_id- endpoint id (slug) to which the webhook will be delivered (Required)
headers- a key value map which will be appended to request headers (Optional)
payload- a custom valid JSON object to be sent as request body (Optional)
method- a HTTP method to use when sending the request (Optional)
Filtering webhook requests»
Filtering and selecting webhooks can be done by using the received input data. Rules can be created where only specific actions should trigger a webhook being sent. For example we could define a rule which would allow a webhook to be sent about any drift detection run:
1 2 3 4 5 6 7 8
Creating a custom webhook request»
All requests sent will always include the default headers for verification, a payload which is
appropriate for the message type and the
method set as
POST. However, by using the webhook rule
we can modify the body of the request, change the method or add additional headers.
For example, if we wanted to define a completely custom request for a tracked run we would define a rule like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
Using custom webhook requests also makes it quite easy to integrate Spacelift with any third-party webhook consumer.
Custom webhook requests in action»
Discord can be integrated to receive updates about Spacelift by simply creating a new webhook endpoint in your Discord server's integrations section and providing that as the endpoint when creating a new named webhook.
For more information about making Discord webhooks follow their official webhook guide.
After creating the webhook on both Discord and Spacelift you will need to define a new webhook rule like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
And that's it! You should now be receiving updates about tracked runs to your Discord server: