Versions Compared

Version Old Version 10 New Version 11
Changes made by

Jay Crouch (Unlicensed)

Jay Crouch (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • Call.create

  • Call.update

  • ScenarioSession.create

  • ScenarioSession.update

In the near future (Q2 or Q3 of 2021'), Scope will be adding the events listed in this document.

Webhook format

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

An example payload follows:

Code Block
{
  "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": "scenarioScenario"
  }
}

Where, at this time, :

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

Note

Use updated events at your own risk.

Unlike most other events (e.g. created, finished, paused), updated events are subject to change without notice because internal business logic changes with every Scope release, and

...

updated events trigger every time a record changes state in Scope data stores.

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:

Code Block
{
  "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 the a resource.

See Using Global Node Ids and Exploring the Graph.

Most relationships (aka “Connections”) are bidirectional in the Scope GraphQL API. This means that given a node in the graph, you can usually to navigate “up” to find parent-like objects (such as organization, viewer, or scenario) as well as as “down” to find child-like objects (such as scenarioSessionEvents, or scenarioSessionCheckboxes).

Examples

Given the following webhook:

Code Block
{
  "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?”:

Code Block
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?”:

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