Change Notifications

When certain data in XOi Cloud changes, notifications can be sent to a configured notification URL (a webhook). This allow integrations to take action based on these changes.

Job Triggers

Notifications will be sent when the following updates to a job occur in XOi Cloud:

a job is completed.
a workflow on a job is finished (even if the job itself is not yet completed)
a completed job is updated, either by an individual or due to an automated process such as transcription or dataplate recognition.
a finished workflow is updated (again, even if the job containing the workflow is not yet completed.)
a job is deleted.

Notifications sent based on a change to a workflow will include the jobId for the job associated with the workflow as well as the workflowJobId for the workflow that was updated.

Although deleting a job will result in a job_deleted notification being sent, removing a workflow will not. If the job was already completed, it will result in a job_updated notification.

NOTE: With the introduction of the multiple workflows per job feature, webhooks may now be notified prior to the completion of a job. This is to allow integrations to react to a finished workflow prior to the completion of the job as a whole.

See the technical notes for additional information regarding and the new multiple workflows per job feature.

Example Notification

Notifications will take the form of a JSON payload transmitted via a POST request to the registered webhook URL:

{
  "orgId": "a-vision-org-id",
  "event": "job_update",
  "jobId": "job-1234567890abcdef1234567890-xiwh",
  "workflowJobId": "",
  "traits": ["dataplate", "transcript", "processed", "pending", "not_a_dataplate"],
  "firedAt": "2020-03-18 18:49:20"
}

event identifies the change within XOi Cloud that resulted in the notification. There are currently two event types for jobs: job_update and job_delete.
jobId identifies the job to which the change applies. This ID can be used to retrieve detailed information about the job from the XOi Cloud API.
workflowJobId identifies the workflow that was updated if such a change triggered the notification. This will be blank if the notification was triggered by a change to a Container Job.
traits provide some insight into the job itself and can be used for basic filtering of events. See the Job API Guide for more information regarding possible traits and how they are derived.
firedAt provide the date and time this event was fired

Note that the traits list includes a roll-up of all traits as they exist on items within the workflow that triggered the change. So in the example above, the updated workflow might contain a documentation item for which dataplate recognition is complete with no dataplate recognized and another documentation item for which transcription is still being processed, resulting in that particular set of traits.

If a change event is sent as a result of a modification to a _Container Job, no traits will be included, as Container Jobs have no documentation items directly._

Retrieving Webhook Notification History

As an alternative to hosting a webhook or as a supplement to doing so, it is possible to query for notifications that were sent to the webhook endpoint(s) configured for a given organization. It is also possible for XOi to configure an organization to only write to this history, forgoing the actual webhook notification.

This query is part of the Jobs API. The relevant API URLs are the same as for the Jobs API:

Testing: https://gql-jobs-external.staging.xoeye.com/graphql
Production: https://gql-jobs-external.xoi.io/graphql

NOTE When requesting webhooks you might run into a scenario where you are given more results on subsequent calls than on the first. This is due to the pagination. The presence of nextToken is the best indication of whether you still have more webhooks to retrieve or not

Example Request

See the ListWebhookHistory schema for the details of what is required for this request.

query ListWebhookHistory {
  listWebhookHistory(
    input: {
      limit: 5
      dateQuery: { gte: "2020-09-01T00:00:00.00000Z", ascending: true }
      nextToken: ""
    }
  ) {
    webhookHistoryConnection {
      nextToken
      items {
        jobId
        workflowJobId
        orgId
        firedAt
        event
        traits
      }
    }
  }
}

Example Response

See the ListWebhookHistoryResult schema for the details of what to expect in your response. Notice that the payload is documented above.

{
  "data": {
    "listWebhookHistory": {
      "webhookHistoryConnection": {
        "nextToken": "",
        "items": [
          {
            "jobId": "cjob-i023494aabdb54dd1b5e5b791b192ed2b-abc0",
            "workflowJobId": "wjob-i4aabdb54dd1b5e5b791b192ed2b02349-abc0",
            "orgId": "a-vision-org-id",
            "firedAt": "2020-09-01T12:34:24.146094Z",
            "event": "job_update",
            "traits": null
          },
          {
            "jobId": "cjob-i023494aabdb54dd1b5e5b791b192ed2b-abc0",
            "workflowJobId": "wjob-i4aabdb54dd1b5e5b791b192ed2b02349-abc0",
            "orgId": "XOi",
            "firedAt": "2020-09-01T12:34:27.687336Z",
            "event": "job_update",
            "traits": null
          },
          {
            "jobId": "cjob-i023494aabdb54dd1b5e5b791b192ed2b-abc0",
            "workflowJobId": "wjob-i4aabdb54dd1b5e5b791b192ed2b02349-abc0",
            "orgId": "XOi",
            "firedAt": "2020-09-01T12:34:33.941849Z",
            "event": "job_update",
            "traits": null
          }
        ]
      }
    }
  }
}

Content Trigger

Notifications will be sent when the following updates to a piece of content occur in XOi Cloud:

a content is uploaded

Note that any item of content that gets uploaded or updated at this time will not fire off a webhook if it is not tied to a vision live call.