v1

Notifications /

Create a webhook integration

You can create a webhook notification integration to send events to a HTTP endpoint for processing. This can be a powerful tool for automating workflows involving Northflank, especially when combined with the Northflank API.

You can create or update a webhook integration from the notifications page in your account/team settings.

Select the webhook integration type and enter your webhook URL, and your secret (if required). You can update these later.

You can select the types of event you want to receive notifications about and choose to only receive notifications about events in specific projects, if required.

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 succeeded, so your app can download the backup via the Northflank API and store it in an off-site backup system

Webhook secret

You can add a secret to your webhook to ensure the request originated from your Northflank notification integration.

Either generate a secret yourself, or generate one on Northflank using the random secret generator in the form field.

You can then add this secret to your webhook endpoint application. If your workload is deployed on Northflank, you can add it either as a runtime variable or in a secret file.

The secret will be sent to your endpoint as the X-Northflank-Notification-Integration-Token header. You can compare the value in the header to your secret to confirm the webhook request is legitimate.

Request format

Notifications are sent to webhooks as POST requests containing the following:

Headers

  • X-Northflank-Notification-Integration-Id - ID of the notification integration that the request originated from
  • X-Northflank-Notification-Integration-Name - Name of the notification integration that the request originated from
  • X-Northflank-Notification-Integration-Token - Secret associated with the notification integration that the request originated from.
  • X-Northflank-Notification-Integration-Event-Id - ID of the event contained within the request
  • X-Northflank-Notification-Integration-Event-Type - Type of 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 or the limit is reached.

Webhooks that continuously fail to handle notifications successfully will be automatically disabled.

Recent events

You can find a list of all requests sent to your webhook and their current status when viewing the webhook notification integration.

Click on a specific request to see the request headers and body, as well as a list of the responses received and their status code.

Failing webhooks will be automatically resent several times, and you can also manually resend a webhook request from the event page.

You can expand a response to see the webhook URL, response headers and response body.

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.