Summary

This article describes technical specifications supported by webhooks and guides you through the process of setting up a webhook in Backstage.

Overview

Webhooks allow you to build integrations that react to certain actions users take in their SpotMe apps. When such an action occurs, we'll send a HTTP POST request to the URL you have configured.

Webhooks in Backstage can be setup only by organization's administrators and apply to
all workspaces of the organization. Administrator setting up the webhook does not have to be a member of these workspaces.

Supported actions

When creating a webhook in Backstage you will be asked to select on which user actions should your webhook URL get called.

Available actions are:

Payloads

Each action triggers a HTTP POST request to your configured endpoint. You can find below the standard headers that are sent with the request as well as JSON-encoded body of the request.

Headers

Example payloads

erasure, export and unsubscribe

POST /api/v1/privacy HTTP/1.1
Host: webhooks.acme.inc
User-Agent: SpotMeWebhook
SpotMe-Signature: A5E36019-6F87-4202-BFA3-A5D19EC730CE
Content-Type: application/json
Content-Length: 102

{
  "action": "erasure",
  "id": "1A9AAD96-53D1-43BC-8386-E8BC2DCBB5FE",
  "user_id": "milo@acme.inc"
}

workspace_creation

POST /api/v1/new-workspace-created HTTP/1.1
Host: webhooks.acme.inc
User-Agent: SpotMeWebhook
SpotMe-Signature: A5E36019-6F87-4202-BFA3-A5D19EC730CE
Content-Type: application/json
Content-Length: 102

{
  "action": "workspace_creation",
  "id": "1A9AAD96-53D1-43BC-8386-E8BC2DCBB5FE",
  "event_id": "1A9AAD96-53D1-43BC-8386-E8BC2DCBB5FE"
}

Configuration

Creating a new webhook

1. Click Organizations tab on your Backstage dashboard
2. Click on the name of your organization in the organization list
3. Click on Webhooks tab

   Only administrators can configure webhooks

4. Click on Add a webhook button
5. Fill out the webhook details
   1. Label: will be displayed in Backstage to identify different webhooks
   2. Endpoint URL: this is the HTTP endpoint that will be called
   3. Secret: an optional string that will be sent to the HTTP endpoint to verify authenticity of the request
   4. Actions to trigger: select one or multiple triggers
   5. Active: disable the webhook if it's not ready yet
6. Click Save