Outgoing Notifications

When your Gatsby site is built and/or deployed on Gatsby Cloud, you now have the option to hook up a set of outgoing notifications about the status of that build. You can send notifications via:

1. a generic webhook
2. a webhook that sends a Slack message
3. Pull Request comments in GitHub or GitLab

By default, the Pull Request comments are already set up for existing and new sites in Gatsby Cloud.

Adding Webhook Notifications

First, navigate to Site Settings. In the sidebar menu under General, select Outgoing Notifications. Then click Add Notification and choose the Webhooks option.

Next, you will be prompted to add a webhook that will receive the payload of information about your build or deploy. There are the following options for event notifications:

• build succeeded
• build failed
• build timed out
• preview succeeded
• preview failed
• preview timed out
• deploy succeeded
• deploy failed

Paste your webhook into the Outgoing webhook URL field, choose an Event to listen to, then click Save. If you want to trigger notifications for multiple events, add a new notification for each.

Webhook Message Payload

You can expect the message payload to appear as follows:

{
  "body": "Markdown message similar to PR comment",
  "buildId": "string-id-of-your-build",
  "workspaceName": "your-workspace-name",
  "siteName": "your-project-name",
  "deployPreviewUrl": "https://your-project.staging-previews.gtsb.io",
  "logsUrl": "https://staging.gtsb.io/dashboard/{workspace-id}/sites/{site-id}/builds/{build-id}/details",
  "duration": "time-of-build",
  "resourceId": "UUID of resource",
  "resourceType": "SITE",
  "event": "BUILD_SUCCEEDED"
}

Adding Slack Notifications

To take advantage of Slack notifications, you first need to create a custom Slack application to handle the webhook message.

First, visit https://api.slack.com/apps?new_app=1 to add a new Slack app. Add one for a workspace where you have appropriate permissions.

Next, add the Incoming Webhook feature and activate it. Then, at the bottom of that page, click Add New Webhook to Workspace

Now, select an appropriate channel for your notifications and click Allow

After that, you will see a success message and a new webhook URL will be generated. Copy the webhook URL.

Finally, return to Gatsby Cloud and navigate to the Outgoing Notifications settings. Click Add Notification and choose the Slack option. Paste the Slack application's webhook URL that you previously copied into the Outgoing webhook URL field.

Choose which Event to listen to and then click Save. You can reuse the same Slack application webhook for all four event types.  If you want to send a notification to multiple channels, you must generate additional webhook URLs for your Slack app and create additional notifications as described above.