Overview

With webhooks, you can set up a notification system that Onboardbase will use to send you updates on certain request that you make to our APIs.

Creating a Webhook URL

Your webhook URL has to be a POST endpoint that Onboardbase can send updates to. We will be sending updates in JSON format, that means that the endpoint needs to parse the JSON request. The endpoint should also return a 200 OK response to acknowledge receiving the updates.

Types of events

We currently raise the following events, the list will continue to grow as we extend our webhook functionality.

Event	Description
ENVIRONMENT_UPDATED	An environment's name was updated
SECRETS_UPDATED	A secret stored on Onboardbase has been updated
SECRETS_CREATED	A new secret was added, we include the ID of the new secret in the payload
SECRETS_DELETED	A secret was deleted, we include the ID of the affected secret in the payload
SECRETS_UPSERTED	A secret was added or updated from one of our integrations: Vercel, Netlify, Heroku

Supported Events

{
  "team": { "name": "Docmini" },
  "project": {
    "name": "dockerized-nodejs-application",
    "description": "A simple dockerized Application",
    "createdAt": "2023-03-28T06:29:12.611Z"
  },
  "environment": {
    "title": "development",
    "createdAt": "2023-03-28T06:29:12.611Z"
  },
  "eventType": "ENVIRONMENT_UPDATED"
}

{
  "team": {
    "name": "Docmini"
  },
  "project": {
    "name": "dockerized-nodejs-application",
    "description": "A simple dockerized Application",
    "createdAt": "2023-03-28T06:29:12.611Z"
  },
  "environment": {
    "title": "development",
    "createdAt": "2023-03-28T06:29:12.611Z"
  },
  secretIds: ["id1"],
  "eventType": "SECRETS_UPDATED"
}

{
  "team": {
    "name": "Docmini"
  },
  "project": {
    "name": "dockerized-nodejs-application",
    "description": "A simple dockerized Application",
    "createdAt": "2023-03-28T06:29:12.611Z"
  },
  "environment": {
    "title": "development",
    "createdAt": "2023-03-28T06:29:12.611Z"
  },
  secretIds: ["id1"],
  "eventType": "SECRETS_CREATED"
}

{
  "team": {
    "name": "Docmini"
  },
  "project": {
    "name": "dockerized-nodejs-application",
    "description": "A simple dockerized Application",
    "createdAt": "2023-03-28T06:29:12.611Z"
  },
  "environment": {
    "title": "development",
    "createdAt": "2023-03-28T06:29:12.611Z"
  },
  secretIds: ["id1"],
  "eventType": "SECRETS_DELETED"
}

{
  "team": {
    "name": "Docmini"
  },
  "project": {
    "name": "dockerized-nodejs-application",
    "description": "A simple dockerized Application",
    "createdAt": "2023-03-28T06:29:12.611Z"
  },
  "environment": {
    "title": "development",
    "createdAt": "2023-03-28T06:29:12.611Z"
  },
  secretIds: ["id1", "id2"],
  "eventType": "SECRETS_UPSERTED"
}

Verifying Webhook Signatures

You can verify the events that Onboardbase sends to your webhook endpoints. Alongside the event body we send, we also include a x-onboardbase-signature Header in the webhook events.

A HMAC SHA512 signature of the event payload signed with your Signing Secret is the value of this header. Before processing any event, the header signature should be checked.

const express = require("express");
const crypto = require("crypto");
const app = express();
app.use(express.json());

function GenerateSignature(secret, body) {
    const stringifyBody = JSON.stringify(body);
    return crypto
      .createHmac('sha512', secret)
      .update(stringifyBody)
      .digest('hex');
}

const signingSecret = process.env.SIGNING_SECRET;
app.post("/webhook", async (req, res) => {
  const signature = req.headers["x-onboardbase-signature"];
  const generatedSignature = GenerateSignature(signingSecret, req.body);
  // check that the signature is valid before processing the event
  if(signature === generatedSignature) {
    // process the webhook event
  }
  res.json({
    status: "success",
    message: "Webhook received",
  });
});

const port = process.env.PORT
app.listen(port, () => {
  console.log(`Webhook listening on port ${port}`);
});

How to Get Your Signing Secret

The signing secret depends on how the webhook was created. If the webhook is tied to an Oauth Client i.e the webhook was created via our Public API and you are getting the webhook on behalf of a user via an Oauth Client. The signing secret in this case is the Client Secret of the Oauth Client.

If the webhook isn't tied to any Oauth Client, then the signing secret will be the value of the Signing Secret on your Onboardbase profile. You will find this by clicking on your avatar on the top right and selecting Manage your account