Webhook Notifications

Summary

Webhook notifications allow an application to register to receive notifications of certain events that occur within the Onshape environment. To receive a notification, an application must expose an endpoint that Onshape can call.

Example Code

Events

Each type of event that an application may receive notifications for has a unique identifier known as the event type. Event types are grouped into Event Groups. Each group shares specification requirements, as described below.

Event Groups

Event types are categorized into several different groups based on the dominant user resource of the event. The group that a given event is part of defines the required parameters needed in the registration process to identify the resource or group of resources to watch. For instance, if registering for an event in the document event group, the application must identify either a specific document’s id or a specific company’s id. If registered for a company, the event will be registered for all present and future documents owned by the company.

Application Group

Monitor changes to applications.

Registration Requirements
  • clientId
Supported Event Types
  • onshape.user.lifecycle.updateappsettings - occurs when user application settings are modified

Document Group

Monitor various aspects of document changes.

Registration Requirements
  • documentId OR companyId must be specified in the registration body.

Note: only documentId is valid for the onshape.document.lifecycle.statechange.

Supported Event Types
  • onshape.model.lifecycle.changed - occurs when a change to a model has been made
  • onshape.model.translation.complete - occurs when a translation request is completed
  • onshape.model.lifecycle.metadata - occurs when part or element metadata is modified
  • onshape.model.lifecycle.createversion - occurs when a new version of a document is created
  • onshape.model.lifecycle.createworkspace - occurs when a new workspace is created
  • onshape.model.lifecycle.createelement - occurs when a new element is created
  • onshape.model.lifecycle.deleteelement - occurs when an element is deleted
  • onshape.document.lifecycle.statechange - occurs when an document changes state
  • onshape.model.lifecycle.changed.externalreferences - occurs when an external reference changes
  • onshape.document.lifecycle.created - occurs when a document is created
  • onshape.revision.created - occurs when a revision is created
  • onshape.comment.create - occurs when a comment is created in a document
  • onshape.comment.update - occurs when a comment is updated in a document
  • onshape.comment.delete - occurs when a deleted is deleted in a document

Workflow Group

Monitor release management actions.

Registration Requirements
  • companyId
Supported Event Types
  • onshape.workflow.transition - occurs when a revision or release package transitions through workflow states.

Lifecycle Group

Monitor webhook changes.

Registration Requirements

No requirements. This event type responds to any and all webhooks registered by the same application.

Supported Event Types
  • webhook.ping - occurs either in response to a request by an application to call a registered webhook, or as a post-registration validation initiated by Onshape
  • webhook.register - occurs in response to a notification registration API call
  • webhook.unregister - occurs in response to a notification deregistation API call

Webhook Registration

An application registers for event notification by making a REST call to the Onshape web service, providing a URL to notify, and the required parameters for the event types to be registered, as mentioned in Event Groups. If the registration request is well-formed, the registration API call returns information about the registration, including a unique ID string. This ID string identifies the webhook registration. No de-duplication of notification registrations is performed by the API. Each registration call will yield a new registration ID, even if the parameters are identical to those passed in a prior call. Shortly after an application calls the notification registration API, Onshape will make make an asynchronous trial notification call to the URL generated from the URL template with an event type of webhook.register in order to test whether the application notification server is accessible. If the trial notification delivery fails to return an HTTP 200 status code, the notification registration is cancelled. The trial notification is usually delivered after the notification registration has been received by the application. However, variations in network delays may result in the trial notification occurring before response is received and processed by the application, so the notification handler should be ready to process notifications before the registration call is made.

Notifications

Notifications are delivered to an application as an HTTP POST with a JSON body. The body includes information about the identity of the registration request plus information specific to the event and notification message. An application may register for notifications to a URL that uses either HTTP or HTTPS. If HTTPS is specified by the URL template, the notification server must supply a certificate that is signed by a certificate authority (CA) recognized by Onshape.
Self-signed certificates as well as certificates signed by unrecognized CAs will be rejected, causing notification delivery to fail.

Notification Deregistration

When an application no longer needs to be notified of changes specified by a particular notification registration, it should normally de-register the notification request. De-registration is performed by making an HTTP that specifies the hook to deregister. Onshape will attempt to call the deregistered hook with an event type of webhook.unregister as validation for the application that the de-registration is complete. If the application does not de-register the webhook, Onshape will continue delivering notifications until either the the application returns an error in response to a notification for the webhook, or fails to respond at all for an extended period of time.

Notification API example messages

registration

{
  "timestamp": "2014-12-16T23:45:10.611-0500",
  "event": "webhook.register",
  "workspaceId": "000000000000000000000000",
  "elementId": "000000000000000000000000",
  "webhookId": "544e91f7fb88ed44f5de1508",
  "messageId": "34795d2e5f5f44eeb61fb7b1",
  "data": "Some data",
  "documentId": "000000000000000000000000",
  "versionId":  "000000000000000000000000"
}

ping

{
  "timestamp": "2014-12-16T23:46:24.368-0500",
  "event": "webhook.ping",
  "workspaceId": "000000000000000000000000",
  "elementId": "000000000000000000000000",
  "webhookId": "544e91f7fb88ed44f5de1508",
  "messageId": "6808d9a622644330b6cd95f5",
  "data": "Some data",
  "documentId": "000000000000000000000000",
  "versionId":  "000000000000000000000000"
}

model change

{
  "timestamp": "2014-12-16T23:46:29.284-0500",
  "event": "onshape.model.lifecycle.changed",
  "workspaceId": "f925722bee1c43fc80fb5bb2",
  "elementId": "0f931a1ceba842299192823f",
  "webhookId": "544e91f7fb88ed44f5de1508",
  "messageId": "60f54ac1cbc04179a6642d9a",
  "data": "Some data",
  "documentId": "0f9c4392e5934f30b48ab645",
  "versionId":  "000000000000000000000000"
}

document state change

{
  "timestamp": "2014-12-16T23:46:29.284-0500",
  "event": "onshape.document.lifecycle.statechange",
  "workspaceId": "000000000000000000000000",
  "elementId": "000000000000000000000000",
  "webhookId": "544e91f7fb88ed44f5de1508",
  "messageId": "60f54ac1cbc04179a6642d9a",
  "data": "Some data",
  "documentId": "0f9c4392e5934f30b48ab645",
  "versionId":  "000000000000000000000000",
  "documentState": "TRASH"
}

Possible values of documentState are:

  • “ACTIVE” - document is in a normal, usable state
  • “TRASH” - document has been moved to the trash (User can move out of trash to ACTIVE state)
  • “DELETED” - document has been deleted

user application settings change

{
  "timestamp": "2014-12-16T23:46:29.284-0500",
  "event": "onshape.user.lifecycle.updateappsettings",
  "workspaceId": "f925722bee1c43fc80fb5bb2",
  "elementId": "0f931a1ceba842299192823f",
  "webhookId": "544e91f7fb88ed44f5de1508",
  "messageId": "60f54ac1cbc04179a6642d9a",
  "data": "Some data",
  "userId": "567953d60a1a5fbb95940333",
  "clientId":"ABCDEFGHIJKLMNOPQRSTUVWXZY234567ABCDEFG="
}

translation completion

{
  "timestamp": "2014-12-16T23:46:29.284-0500",
  "event": "onshape.model.translation.complete",
  "workspaceId": "f925722bee1c43fc80fb5bb2",
  "elementId": "0f931a1ceba842299192823f",
  "webhookId": "544e91f7fb88ed44f5de1508",
  "messageId": "60f54ac1cbc04179a6642d9a",
  "data": "Some data",
  "documentId": "0f9c4392e5934f30b48ab645",
  "userId": "567953d60a1a5fbb95940333",
  "translationId": "4f5de10f9c4392e5934f30b4"
}

comment create

{
  "timestamp": "2014-12-16T23:46:29.284-0500",
  "event": "onshape.comment.create",
  "workspaceId": "f925722bee1c43fc80fb5bb2",
  "elementId": "0f931a1ceba842299192823f",
  "webhookId": "544e91f7fb88ed44f5de1508",
  "messageId": "60f54ac1cbc04179a6642d9a",
  "documentId": "0f9c4392e5934f30b48ab645",
  "commentId": "567953d60a1a5fbb95940333"
}