Using WebHooks

Webhooks allow Scope Customers and 3rd party integrators to build Applications that import data and/or execute custom code after specific events occur in the Scopear.com ecosystem.

For example, as a Scope Customer, you might want to use a webhook to trigger a custom action that downloads ScenarioSession data 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.

Also known as “Service Hooks”.

In this article

Requirements

• Your organization must be an active Scope customer.

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

• You must have previously authenticated with the Scope GraphQL API.

What is a webhook?

• A Webhook is a single HTTP POST request that is sent by a web server to a url that you specify, and is typically triggered by the occurrence of a specific, predefined type of 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.

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 user status in your system-of-record (e.g. when users complete Scope Scenarios)

Anatomy of a webhook

After you subscribe to a webhook topic, Scope sends a webhook notification to the specified callback url each time an event occurs pertaining to the specified topic. This notification is an HTTP POST request that contains a JSON payload, and HTTP headers that provide context.

For example, the scenario_session/create webhook notification includes the following:

Headers

• X-Scope-Topic: scenario_session/create

• 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

Some HTTP headers are particularly useful for your app. For example, X-Scope-Hmac-Sha256 is used to verify the authenticity of webhooks, X-Scope-Webhook-Id is used to troubleshoot webhooks, and X-Scope-Domain is used to identify the system that sent the webhook.

At this time, the value of X-Scope-Webhook-Type is always node. However, in the future we hope to introduce additional webhook types that pertain to events that do not involve GraphQL nodes (e.g. a value of service might indicate that a particular service has become available.

Body

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

Where:

• 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.

Customizing the payload

By design, the default JSON payloads provide limited information in order to encourage integrators to query the Scope GraphQL API for the specific information that they require (i.e. information about a ScenarioSession in this example).

See Acting on webhook data to learn more.

In lieu of querying the Scope GraphQL API for additional data, you can supply a valid GraphQL query (for the server to execute on your behalf) when creating or updating a webhook subscription.

If a query is supplied to a webhook subscription, it will be executed by the server when preparing each relevant webhook notification for delivery, and the result of that execution will replace the default JSON payload.

By way of example, to customize the payload for a scenario_session/completed webhook subscription, you could supply the following query:

query {
  node(id: "t5V3S3X8Trt/weWu0A2YHb0cRFJfcRA2rXT3vAGTz1A=")
    ... on ScenarioSession
      startedAt
      endedAt
      duration
      state
      parts {
        nodes {
          id
          duration        
        }
      }
    }
  }
}

List of available webhook topics

Every GraphQL Object Type that implements the Node Interface triggers created, updated, and deleted events. Additionally, the following special 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

Alternatively, you can retrieve the list of currently available topics (at any time) by executing the following query against the Scope GraphQL API:

query {
  webhookTopics {
    nodes {
      key
      version
      disabled_at
    }
  }
}

Configuring your app

To receive webhooks, register a HTTPS endpoint with your app as a webhook receiver. Then, create a webhook subscription specifying said endpoint and the webhook topic that you wish to receive webhook notifications about. Scope will send your app a JSON payload whenever an event for the subscribed topic occurs. The default payload contains the object id that triggered the event.

Webhook subscriptions are scoped by the user and organization that they're registered to. This means that when a webhook subscription is registered: a) other users & organizations can't view, modify, or delete it; and b) other subscriptions will not be triggered by events pertaining to your data.

Versioning

The header X-Scope-API-Version specifies the version of the Scope GraphQL API that was used to serialize the webhook event payload.

The headers X-Scope-Topic & X-Scope-Topic-Version specify the topic that triggered the webhook.

Subscribing to a webhook topic

You can subscribe to a webhook topic by running the createWebhookSubscription mutation in GraphQL.

The following example shows how to subscribe for the scenario_session/create webhook topic.

GraphQL Query

mutation {
  createWebhookSubscription(    
    webhookSubscription: {
      topic: { key: 'scenario_session/create' }
      callbackUrl: "https://my-custom-application.com/hooks/scopear"
      sharedSecret: "SOME SUPER SECRET STRING"
    }
  ) {
    errors {
      field
      message
    }
    webhookSubscription {
      id
    }
  }
}

JSON response

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

Testing webhooks

When testing webhooks, you can run a local server or use a publicly available service such as Beeceptor. If you decide to run a server locally, then you need to make it publicly available using a service such as Pagekite or ngrok. The following URLS do not work as endpoints for webhooks:

• Localhost

• Domains like www.example.com

Creating an endpoint for webhooks

Your endpoint needs to be an HTTPS webhook address 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 a five second timeout period and a retry period for subscriptions. 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-Shopify-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 Shopify, compute the HMAC digest according to the following algorithm and compare it to the value in the X-Shopify-Hmac-SHA256 header. If they match, then you can be sure that the webhook was sent from Shopify. 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 Shopify 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_SHOPIFY_HMAC_SHA256"])

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

Filtering webhooks

If you use a single endpoint (aka “callback_url”) to receive multiple subscriptions, you will need to filter requests using the headers.

The following Ruby example assumes you are only interested in handling updated events for ScenarioSession resources:

#!/usr/bin/ruby

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

Best practices

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

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.

Acting on webhook data

Upon receiving an HTTP POST to your webhook URL, you may want to query the API for additional information associated with a resource.

See Using Global Node Ids and Exploring the Graph.

Examples

Given the following webhook:

{
  "time": "2020-10-20T18:06:02Z",
  "event": "create",
  "type": "resource",
  "data": {
    "resource-id": "OiSSdfK1Su4gwG4zAi2InavDB9eRE9aOnGHYRMG5dqY=",
    "resource-url": "https://cms.scopear.com/api/v3/graphql/object/w4Aa1bjiiNSt1StG11n40b4dYU8lAigrCalO8r6cYwYchxAsWytj-F6wojhI_CsN",
    "resource-type": "ScenarioSession"
  }
}

An integrator could query the API to answer the question “what Scenario is associated with this ScenarioSession?”:

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

Or, an integrator could query the API as follows to answer the question “what ScenarioSessionEvents are associated with this ScenarioSession?”:

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