Webhooks Developer Guide

Developer
1

Webhooks Developer Guide

As of Q3 2024, Developers using Bluescape’s API can now utilize webhooks for more efficient workflow automation. Webhooks allow you to pre-assign a webhook endpoint to call when a specified event happens in a bluescape workspace. Prior to this feature being released, developers had to create GraphQL subscriptions for all events in a workspace and parse the ones they cared about. Webhooks make it easier to trigger custom workflows with external applications or services to enhance the Bluescape experience.

Enabling webhooks

To utilize webhooks, you will first need to enable them in your Bluescape instance.

For commercial/SaaS customers, reach out to your Bluescape point of contact to enable them for your instance and organization.

For on-prem / private instance customers, webhooks are enabled by default at the instance level, but each org still needs to enable them through the CLI.

The bluescape.libsonnet setting to enable or disable webhooks is located at $.sharedConfig.webhooks.enabled - to disable them, set the value to "false".

The CLI commands to issue can be found on our community site.

  1. Get the org id from the CLI by calling organizations (copy the ORG ID for your org).

  2. Update the feature flag is_webhooks_enabled by calling organizations features <ORG ID> -k is_webhooks_enabled=true
    The output will look like:

      [
        {
          "featureFlags": [
            {
              "config": {},
              "createdAt": "2023-10-04T00:00:00.000Z",
              "description": "Controls if Webhooks is enabled",
              "isOverrideRestricted": false,
              "key": "is_webhooks_enabled",
              "name": "Webhooks",
              "updatedAt": "2023-11-12T00:00:00.000Z",
              "value": true,
              "__typename": "FeatureFlag"
            }
          ],
          "id": "<ORG ID>"
        }
        ]
  1. Create your first webhook
    For a webhook to be useful, you need a target. You can use n8n or your own server that listens for a call to it from Bluescape. By default, the webhook request is a POST to the URL you specify. The body of the POST will be the workspace event details including the elementId, actorId, and event type and data.
    To create a webhook, you can make a POST request to the REST api at https://api.<domain>/v3/webhooks/workspace/<workspace id> with the body:
{
  "callbackUrl": "https://<your callback url>"
}

You can also send additional parameters to limit the scope of your workspace events. You can pass in an elementId or elementType. elementId will track any changes to a single element, but elementType will track all changes to that type of element (e.g. Canvas) in a workspace.

Available element types

The following element types are supported in the webhooks API:
"Text" "LegacyNote" "Icon" "Image" "Document" "Grid" "Browser" "Video" "Stroke" "Shape" "Line" "LinkedDocument" "Canvas" "Selection" "Window"

Handling events

Your n8n workflow or custom server should now be able to read the body of the webhook and perform actions accordingly.

Where to Next?

Not what you were looking for? Reply below or Search the community and discover more Bluescape.

Q4 2024 Release Notes Summary
Q3 2024 Release Notes Summary