v1

Notifications /

Webhooks

The webhook notification integration type can be used to send notifications when events, such as build failures, occur on the Northflank platform to a HTTP endpoint for processing. This can be a very powerful tool for automating workflows involving Northflank, especially when combined with the Northflank API.

Example Use Cases

You could use a webhook notification integration to alert your app:

  • That a job has failed, so your app can create a ticket in your bug tracking software.
  • That a backup has completed, so your app can download the backup via the Northflank API and store it in an off-site backup system.

Request Format

Notifications are sent to webhooks as POST requests containing the information documented below.

Headers

Requests contain the following headers:

  • X-Northflank-Notification-Integration-Id - The id of the notification integration the request originated from.
  • X-Northflank-Notification-Integration-Name - The name of the notification integration the request originated from.
  • X-Northflank-Notification-Integration-Token - The secret associated with the notification integration the request originated from. You can compare this value to that found in the Northflank app to ensure the request originated from your notification integration.
  • X-Northflank-Notification-Integration-Event-Id - The id of the event contained within the request.
  • X-Northflank-Notification-Integration-Event-Type - The type of the event contained within the request, e.g. build:start.

Body

Requests contain a JSON encoded body containing the following properties:

  • event - The type of the event, e.g. build:start.
  • data - An object containing data related to the event.

The following is an example of the data you may receive in the body of the request when a build is started:

{
  "event": "build:start",
  "data": {
    "build": {
      "id": "social-hour-1312",
      "branch": "master",
      "pullRequestId": null,
      "status": "STARTING",
      "sha": "ca624abed0d5ba0ad6e6fe28c396196b81f0200d",
      "concluded": false,
      "createdAt": "2022-01-19T09:04:40.916Z"
    },
    "service": {
      "id": "website",
      "name": "Website"
    },
    "project": {
      "id": "personal-blog",
      "name": "Personal Blog"
    },
    "user": {
      "id": "thomas"
    }
  }
}

Error Handling

To indicate a webhook has successfully handled a notification it should respond to the request with a 2xx status code. If a webhook does not respond with a 2xx status code the associated notification integration will be marked as Failing and the notification will be resent a limited number of times until it is handled successfully. Webhooks that continuously fail to handle notifications successfully will be automatically disabled.

To assist you with debugging webhooks, a list of all requests sent to your webhook and their response, including those from resent requests, can be seen when viewing a notification integration in the notifications section under integrations in your account settings. Through this list you can also manually request a notification is resent.

Example Webhook Handler

The following is an example of a webserver, written using Express, that handles notifications sent via a webhook:

// This example uses Express to setup a webserver to receive webhooks.
const express = require('express');
const app = express();
app.use(express.json());

// Setup an endpoint to receive webhooks.
app.post('/webhook', (request, response) => {
  // Check the request originated from Northflank and reject any that do not.
  const receivedSecret = request.get('X-Northflank-Notification-Integration-Token');
  const actualSecret = process.env.NOTIFICATION_INTEGRATION_SECRET;

  if (receivedSecret !== actualSecret) {
    response.sendStatus(401);
    return;
  }

  // Handle the different events.
  const { event, data } = request.body;

  switch (event) {
    case 'build:start':
      const { project, service, build } = data;
      console.log({ project, service, build });
      // Then define and call a method to handle the event.
      // handleBuildStarted(project, service, build);
      break;

    // ... handle other events.
    default:
      console.log(`Unhandled event ${event}.`);
  }

  // Flag the notification as being handled successfully.
  response.sendStatus(200);
});

// Start the webserver.
app.listen(3000, () => console.log('Running on port 3000.'));

© 2022 Northflank Ltd. All rights reserved.