Webhooks

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

Webhooks allow you to build integrations that react to certain actions that 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 only be set up by organization administrators, and apply to
all workspaces of the organization. The 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.

The 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 the 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 on the Organizations tab on your Backstage dashboard.
   
   
2. Click on the name of your organization in the organization list.
   
   
3. Click on the Webhooks tab. Remember that 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 on Save to confirm.