Using WebHooks

Webhooks allow you to build or set up Applications which subscribe to certain events on Scopear.com.

Webhooks provide a way for notifications to be delivered to an external web server whenever certain actions occur on an organization. Also called a service hook.

In this article

Enabling webhooks for your organization

Contact support and request that a Scope Admin enable webhooks for your organization.

You’ll need to specify the url of the listener that you want to receive Scope event notifications, e.g. something like https://yourapplication.com/hooks/scopear

For example, if you are only interested in handling update events for ScenarioSession resources, you probably want to structure your listener as follows (see Webhook format for more info):

#!/usr/bin/ruby

# @payload: hash
def handleWebook(payload)
  return unless payload['event'] == 'update' &&
    payload['type'] == 'resource' &&
    payload['data']['resource-type'] == 'ScenarioSession'
    
  # process logic goes here...
end

List of available webhooks

The following events currently trigger outbound webhooks. Contact support in order to request the implementation of webhook events additional to those listed below:

• Call.create

• Call.update

• ScenarioSession.create

• ScenarioSession.update

Webhook format

Once webhooks are enabled for your organization, Scope will initiate an HTTP Post to the url you have designated as events occur.

An example payload follows:

{
  "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": "Scenario"
  }
}

Where:

• time is the UTC timestamp when the hook request is triggered (not the timestamp of the event itself)

• event is often one of created, updated, or something more esoteric, like paused, resumed, finished, etc.

• type can only be resource (this value exists for future extensibility, see Event Types)

• resource-id is a valid GraphQL node ID (see Using GraphQL Node Ids)

• resource-url is a thin Rest endpoint that leverages GraphQL internally to deliver 1st level attributes as JSON (a simple fallback for customers that do not want to adopt GraphQL).

• resource-type is a valid GraphQL Object Type (see current published GraphQL API Reference Docs).

Event types

Currently, Scope only supports resource type events because we have yet to identify a compelling use cases that involve data not exposed by the GraphQL API.

That said, we envision a future where Scope might need to notify customers about events that pertain to 3rd party data/systems, and/or data that is not exposed by the GraphQL API.

Non-Resource Events

Webhook consumers/integrations should expect 2nd level fields (those nested under data field) to be conditional based on the value of the type field.

For example, a theoretical future event might look like:

{
  "time": "2020-10-20T18:06:02Z",
  "event": "connected",
  "type": "iot",
  "data": {
    "device_id": "5c4bx0248-28c2",
    "protocol": "MQTT"
    "byte_stream": "3vybr9c047rx4c082bvc5nrxn4c89420w"
  }
}

Where the 2nd level data fields for an iot event might be device_id, protocal, and byte_stream (rather than resource-id, resource-url, resource-type).

Responding to Webhooks

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
        }
      }
    }
  }
}