Webhooks

Automatically notify your application any time certain changes are made to your tenant.

A webhook URL is an endpoint hosted by your application that subscribes to notifications from Gobo. Gobo sends these notifications as events that detail changes to users, organizations, and applications. For example, you can receive an event when a new partner signs up, a partner organization is updated, or an app is installed.

Subscriptions

A Webhook Subscription is created within a Gobo tenant and is where you define the topics on which you want to receive event notifications. A subscription can contain one or more topics. You will need to provide a URL where Gobo will send all notifications for your subscription.

You can view and manage your Webhook subscriptions in the Gobo Dashboard.

Topics

A topic contains one or more event types; for example, the app topic contains the installation, uninstallation, or reinstallation events.

Events

See the Gobo Management API Docs for event definitions.

Notifications

Anytime an event is triggered in a topic to which you are subscribed, Gobo will send an HTTP POST request to your webhook URL in application/json format.

Notifications payloads have the following format:

Notification payload

{
  "event": "event.name",
  "data": {
    …
  }
}

Your application must respond with HTTP status code 200. Otherwise, Gobo will try to resend the notification.

Retry Schedule

Each notification is attempted based on the following schedule, where each period is started following the failure of the preceding attempt:

• Immediately

• 5 seconds

• 5 minutes

• 30 minutes

• 2 hours

• 5 hours

• 10 hours

• 10 hours (in addition to the previous)

If an endpoint is removed or disabled delivery attempts to the endpoint will be disabled as well.

For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.

Disabling failing webhooks​

If all attempts to a specific webhook URL fail for a period of 5 days, sending to that endpoint will be disabled.

Securing your webhooks

Gobo signs webhook notifications via the X-Hub-Signature-256 header. We do this so that you can guarantee that the notification came from Gobo by decoding the signature.

We compute the value of the X-Hub-Signature-256 header by signing the body of the JSON request using your webhook's secret value. You can configure the secret value when setting up your webhook.

The X-Hub-Signature header value starts with the string sha256= followed by the signature. The signature is the hexadecimal representation of the SHA256 signature computed using the HMAC algorithm.

Example webhook verification script:

Node.js Example

const crypto = require("crypto");

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

function verify_signature(req) {
  const signature = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest("hex");
  return `sha256=${signature}` === req.headers.get("x-hub-signature-256");
};

function handleWebhook(req, res, next) {
  if (!verify_signature(req)) return res.sendStatus(401);
  next();
};