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
ORcompanyId
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 madeonshape.model.translation.complete
- occurs when a translation request is completedonshape.model.lifecycle.metadata
- occurs when part or element metadata is modifiedonshape.model.lifecycle.createversion
- occurs when a new version of a document is createdonshape.model.lifecycle.createworkspace
- occurs when a new workspace is createdonshape.model.lifecycle.createelement
- occurs when a new element is createdonshape.model.lifecycle.deleteelement
- occurs when an element is deletedonshape.document.lifecycle.statechange
- occurs when an document changes stateonshape.model.lifecycle.changed.externalreferences
- occurs when an external reference changesonshape.document.lifecycle.created
- occurs when a document is createdonshape.revision.created
- occurs when a revision is createdonshape.comment.create
- occurs when a comment is created in a documentonshape.comment.update
- occurs when a comment is updated in a documentonshape.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 Onshapewebhook.register
- occurs in response to a notification registration API callwebhook.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"
}