Using WebHooks

Webhooks allow integrators to build Applications that execute after specific events occur in the Scopear.com ecosystem.

For example, a Scope Customer might leverage a webhook to trigger a custom action that imports ScenarioSession data into the Customer’s system of record whenever a User completes a session in the Scope Worklink app.

This guide introduces how webhooks work, including how to configure a webhook for your app.

In this article

Requirements

• Your organization must be an active Scope customer.

• Your organization must have provisioned at least one admin User account.

Use cases

Common webhook use cases include the following:

• Collecting data for data-warehousing

• Sending notifications to IM clients and pagers (e.g. when new Scenarios become available)

• Updating state in a system-of-record (e.g. when users complete Scope Scenarios)

See Orchestrating Common Use Cases to see a visualization of webhooks used in connection with other services and components.

What is a webhook?

• A Webhook is a single HTTP POST request that is sent to a url that you specify, and is typically triggered by the occurrence of a specific, predefined event. Scope Webhooks contain a JSON payload in the body and metadata in the headers.
  

• A Webhook Topic is a persisted data object that can be queried in the Scope GraphQL API. Each record describes a specific type of event that triggers a webhook, and is uniquely identified by a key (e.g. “user/created”) and version (e.g. “1.1”).
  

• A Webhook Subscription is also a persisted data object that can be queried in the Scope GraphQL API. Each record describes a webhook topic that you want to receive notifications about, a callback url, and an optional GraphQL query (to be executed during delivery).

Webhook Topics

Created, updated, and deleted topics are available for every GraphQL Object Type that implements the Node Interface (e.g. scenario_session/created, scenario_session/updated, and scenario_session/deleted).

Additionally, the following special use topics are available:

• call/completed

• call_recording/completed

• scenario_session/paused

• scenario_session/resumed

• scenario_session/completed

• scenario_session_part/completed

• scenario_session_step/completed

Creating A Webhook Subscription

Creating a webhook subscription can be done in three (or four) steps using our new interface.

Step One: Navigate to the Webhook page

To begin, click on the Webhooks link under the Develop Tools dropdown menu on the left side navigation.

Step Two: Click on Create Webhook

Clicking on the Webhooks link will bring you to the Webhooks index which lists all the current webhooks created for your organization. Next, click on the Create Webhook button on the far right side of this page.

Step Three: Fill out Mandatory Fields

The Create Webhook button will cause a slide-out form to appear from the right side with several fields. The fields marked with an asterisk ( * ) are mandatory fields. Next to each field should also be a question mark ( ? ) that will give some more info on what each field is.

Name

Give your webhook an informative name by filling in the NAME field.

For our example, the NAME field is set to “Test”:

Topic

A webhook needs an event topic. Select a topic from the TOPIC drop-down list. There are several topics to choose from.

For our example, the topic will be set to the user creation event. That means, this webhook will be sent out every time a user is created in the system:

Content Type

As described earlier, a webhook notification request will have its content type set to JSON by default. However, you can change this to XML by selecting it from the CONTENT TYPE drop-down list.

For our example, the webhook will be JSON:

Callback URL

A webhook notification needs to target a URL. If you want to test out a webhook, you can use webhook.site for the CALLBACK URL endpoint to test with.

For our example, the CALLBACK URL is set to one obtained from webhook.site:

Step Four: Fill out Optional Fields

There are several optional fields that can be used to customize your webhook and provide some additional security.

Integration

If you have any Integrations created, you can associate your webhook to an existing integration. For more information about Integrations, click here.

For our example, we will leave INTEGRATION blank:

Shared Secret

To add some security to your Webhook, you can supply a secret key that will be used to generate a base64-encoded X-Scope-Hmac-SHA256 header. For more information about how to use this, checkout Verifying Webhooks.

For our example, we will input a simple SHARED SECRET:

Query

The query field is super useful. By default, only the ID and the URL will be returned for the node that had been affected:

Default

{
  "data": {
    "id": "t5V3S3X8Trt/weWu0A2YHb0cRFJfcRA2rXT3vAGTz1A=",
    "url": "https://cms.scopear.com/api/v3/graphql/object/t5V3S3X8Trt/weWu0A2YHb0cRFJfcRA2rXT3vAGTz1A="
  }
}

What it does is that it allows for more data to be added to the webhook by allowing a GraphQL query to be ran and the data returned from the query will be used instead. When a query is supplied with a webhook subscription, it will be executed by the server each time that it prepares a notification for delivery, and the result of that execution will replace the default JSON payload.

For example, let’s make the user/created webhook that we just created return the name of the user:

Now, the webhook will be returning different data:

{
  "data": {
    "node": {
      "name": "Alain Bloch"
    }
  }
}

See Sample Queries for more complicated query examples.

Data Validation Template

Suppose you want to validate the data and make a decision on whether to send the webhook request or not. In this field, we can use the Liquid template language to make a conditional statement. This uses the default data or the data generated from the Query field discussed above.

Continuing from our last example, let’s only send a webhook notification if the user’s name is not “Alain Bloch”:

Template

Suppose you want to customize the request body being sent because the default request body isn’t accepted by your webhook callback url. Here we can use the Liquid template language to further customize the body.

For our example, let’s remove the outer data and node objects that the actual data is nested within. Instead, we will return the actual data:

Now, the webhook request will return just the name:

{
  "name": "Alain Bloch"
}

Error Handling Template

By default, if a webhook notification returns a unsuccessful response (anything but a 200 HTTP status code), it will add an error under the Error tab on the webhook. However, sometimes an API will return a successful response but have an error message within the response body. With the Error Handling Template, you can use the Liquid template language to add some conditional statement. Anything returned will be treated as an error. Return nothing if the response is successful.

For example, let’s assume that the API we are interacting with will return a successful response but with an error message inside the response:

{
  "error": "User already exists"
}

In this case, we want to examine the response body for an error and return that message:

Webhook Overview

After creating your webhook, you can click on the webhook in the list of webhooks and be brought to the Webhook Overview page. This shows all the details of the webhook:

Webhook Errors

Any errors that the webhook subscription encounters when it tries to deliver a notification will be displayed under the Error tabs on the webhook page.

Clicking on the link will bring you to the list of errors for that webhook:

Clicking on an error will bring you to the Error Details page. This contains useful information about the webhook error that can be used for debugging purposes:

Removing an Error

If you feel that the error is resolved, you can delete the error by clicking on the box next to the error on the list page and then deleting it.

Testing Webhooks

If you want to test your webhook out, there is an easy way to do it! On the Webhook form, there is a toggle that can be switched on. This toggle will use the last node created for that topic as the example node to be used for delivery. This can have some unexpected results since you might not know what the last node is. Nonetheless, it is a good way to test if the Webhook is working.

Disabling A Webhook

If your webhook isn’t ready or is erroring, you can always disable it (rather than delete it). Use the edit form, and on the bottom of the form is an Enabled webhook toggle. Turn this off to disable the webhook:

Webhook Anatomy

After you Create A Webhook Subscription, Scope sends a webhook notification as an HTTP POST to the specified callback url each time an event occurs for the specified topic.

A webhook notification can be broken down into X Headers, Content Type, and Request Body.

Headers

The headers of a webhook are very specific:

• X-Scope-Topic: Specify the topic that triggered the webhook

• X-Scope-Topic-Version: Specify the version of the topic because topics might mean different things in future versions.

• X-Scope-API-Version: Specifies the version of the Scope GraphQL API that was used to serialize the webhook event payload.

• X-Scope-Domain: Specifies the system that sent the webhook.

• X-Scope-Hmac-Sha256: Used to verify the authenticity of webhooks.

• X-Scope-Webhook-Id: The record ID of the webhook.

• X-Scope-Webhook-Type: Specifies the type of payload being sent

• X-Scope-Webhook-Job-Id: Used for troubleshooting the webhook request.

• X-Scope-Time: UTC Timestamp on when this webhook was sent.

• Content-Type: By default, a webhook will send its payload in a JSON format, and the content-type will be set to application/json in the headers of the request. However, when Creating A Webhook, a webhook can also be specified to be other formats.

Example

X-Scope-Topic: scenario_session/created
X-Scope-Topic-Version: 1.1
X-Scope-API-Version: 3
X-Scope-Domain: scopear.com
X-Scope-Webhook-Type: node
X-Scope-Hmac-Sha256: XWmrwMey6OsLMeiZKwP4FppHH3cmAiiJJAweH5Jo4bM=
X-Scope-Webhook-Id: b54557e4-bdd9-4b37-8a5f-bf7d70bcd043
content-type: application/json

Request Body

The request body of the webhook notification has default but it can be customized. Check out Creating A Webhook for information about to customize the request body.

Default Request Body

• id is a globally unique descriptor that can be used to query the Scope GraphQL API for more information.

• url is a reference to a simple REST representation of the object that can be accessed by HTTP GET.

Example

{
  "data": {
    "id": "t5V3S3X8Trt/weWu0A2YHb0cRFJfcRA2rXT3vAGTz1A=",
    "url": "https://cms.scopear.com/api/v3/graphql/object/t5V3S3X8Trt/weWu0A2YHb0cRFJfcRA2rXT3vAGTz1A="
  }
}

Retrieving more data

By default, Scope delivers minimalistic payloads in order to encourage integrators to query the Scope GraphQL API for the specific information that they require.

GraphQL is a powerful tool that allows integrators to ask for exactly what they need.

See Using Global Node Ids and Exploring the Graph to learn how to use the Scope GraphQL API.

GraphQL Examples

Given the following webhook default data response:

{
  "id": "OiSSdfK1Su4gwG4zAi2InavDB9eRE9aOnGHYRMG5dqY=",
  "url": "https://cms.scopear.com/api/v3/graphql/object/w4Aa1bjiiNSt1StG11n40b4dYU8lAigrCalO8r6cYwYchxAsWytj-F6wojhI_CsN"
}

You could answer the question “What Scenario is associated with this ScenarioSession?” by using the following GraphQL API query:

query {
  node(id: "OiSSdfK1Su4gwG4zAi2InavDB9eRE9aOnGHYRMG5dqY=") {
    ... on ScenarioSession {
      scenario {
        id
      }
    }
  }
}

Or, you could answer the question “What ScenarioSessionEvents are associated with this ScenarioSession?” by querying the Scope GraphQL API as follows:

query {
  node(id: "OiSSdfK1Su4gwG4zAi2InavDB9eRE9aOnGHYRMG5dqY=") {
    ... on ScenarioSession {
      scenarioSessionEvents {
        nodes {        
          id
        }
      }
    }
  }
}

Configuring your app

To receive webhooks, register a HTTPS endpoint with your app to act as a webhook receiver.

Then, subscribe to a webhook topic and supply the endpoint registered in the previous step as the callbackUrl input value. Scope will immediately begin sending your app webhook notifications whenever events occur that pertain to the specified topic.

Creating an endpoint for webhooks

Your endpoint needs to be a valid HTTPS url with a valid SSL certificate that can correctly process event notifications as described below. You also need to implement verification to make sure webhook requests originate from Scope.

Receiving a webhook

After you register a webhook URL, Scope issues an HTTP POST request to the URL specified every time that event occurs. The request's POST parameters contain JSON data relevant to the event that triggered the request.

Responding to a webhook

Your webhook acknowledges that it received data by sending a 200 OK response. Any response outside of the 200 range, including 3XX HTTP redirection codes, indicates that you did not receive the webhook. Scope does not follow redirects for webhook notifications and considers them to be an error response.

Frequency

Scope has implemented both a timeout period and a retry period for delivery. Scope waits five seconds for a response to each webhook request. If there is no response, or an error is returned, then Scope retries the connection 25 retries over the next 21 days.

To avoid timeouts and errors, consider deferring app processing until after the webhook response has been successfully sent.

Verifying webhooks

Each webhook request includes a base64-encoded X-Scope-Hmac-SHA256 header, which is generated using the shared secret you provide when creating a webhook subscription along with the data sent in the request.

To verify that the request came from Scope, compute the HMAC digest according to the following algorithm and compare it to the value in the X-Scope-Hmac-SHA256 header. If they match, then you can be sure that the webhook was sent from Scope. As a best practice, the HMAC digest should be verified before the app responds to the webhook.

The following Ruby example uses the Sinatra web framework to verify a webhook request:

require 'rubygems'
require 'base64'
require 'openssl'
require 'sinatra'
require 'active_support/security_utils'

# The Scope app's shared secret, viewable from the Partner dashboard
SHARED_SECRET = 'my_shared_secret'

helpers do
  # Compare the computed HMAC digest based on the shared secret and the request contents
  # to the reported HMAC in the headers
  def verify_webhook(data, hmac_header)
    calculated_hmac = Base64.strict_encode64(OpenSSL::HMAC.digest('sha256', SHARED_SECRET, data))
    ActiveSupport::SecurityUtils.secure_compare(calculated_hmac, hmac_header)
  end
end

# Respond to HTTP POST requests sent to this web service
post '/' do
  request.body.rewind
  data = request.body.read
  verified = verify_webhook(data, env["HTTP_X_Scope_HMAC_SHA256"])

  # Output 'true' or 'false'
  puts "Webhook verified: #{verified}"
end

Best practices

This section contains some procedures to ensure your webhook integration functions as seamlessly as possible.

Filtering webhooks

After having subscribed to one or more webhook topics. it is your responsibility to filter out unwanted notifications. There is no mechanism available to filter events on the server, nor does Scope intend to ever implement such a feature.

The following Ruby example demonstrates how to filters events (assuming that you are only interested in handling updated events for ScenarioSession resources):

#!/usr/bin/ruby

def filterWebookNotification(headers, body)
  return unless headers['X-Scope-Topic'] == 'scenario_session/updated'
    
  # business logic goes here...
end

Recovering webhooks

In the event that your app goes offline for an extended period of time, you can recover your webhook subscriptions by re-registering (or re-enabling) your webhook subscriptions and importing the missing data.

Re-registering webhook subscriptions

To re-register disabled webhook subscriptions, consult the app's code that initially registered the webhooks. You can add a check that fetches all your active webhook subscriptions and only registers the ones that you need.

Re-enabling webhook subscriptions

To re-enable disabled webhook subscriptions, execute the following query:

GraphQL Query

mutation {
  updateWebhookSubscription(
    webhookSubscription: {
      id: "wMtvO+6DUTQZomQK8MP0Ppsip6hiuTe1TIihz7iadkk="
      disabled: false
    }
  ) {
    errors {
      field
      message
    }
    webhookSubscription {
      id
    }
  }
}

JSON response

{
  "data": {
    "updateWebhookSubscription": {
      "errors": [],
      "webhookSubscription": {
        "id": "wMtvO+6DUTQZomQK8MP0Ppsip6hiuTe1TIihz7iadkk="
      }
    }
  }
}

Importing missing data

To import the missing data, you can fetch data from the outage period and feed it into your webhook processing code.