Webhooks

This page describes the Webhook APIs Onshape provides for working with notifications.

Notifications are delivered to an application as an HTTP POST with a JSON body, which includes information about the identity of the registration request and information specific to the event and notification message.

Webhooks are an alternative approach to polling; instead of your application continuously asking Onshape for new information, webhooks automatically send a notification from Onshape any time an event you are subscribed to occurs.

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.

Webhooks can also have an additional level of authentication. See the Onshape Help: Webhooks page for more information.

ℹ️ Onshape API Notes

  • All Onshape API calls must be properly authenticated.
  • For Enterprise accounts, replace cad in URLs with your company domain.
  • Onshape IDs are written as: {did}, {wvmid}, {eid}, {pid}, {otherId}. See Onshape API Intro for information on what these IDs mean and how to obtain them from your documents.
  • Variables for replacement are written as: {variable1} or <variableTwo>. Never include the braces or angle brackets themselves with these variables.
  • Visit the Learning Center's Intro to the Onshape API course for additional instruction and videos.

Events

Each type of event that an application may receive notifications for has a unique identifier known as the event type.

ℹ️ NOTES

Webhooks you create are automatically cleaned up after a period of inactivity. To prevent this cleanup, set isTransient=false when creating your webhook and unregister the webhook when it is no longer needed.

Supported event types

To view the full list of supported event types and their required request bodies:

  1. Go to the createWebhook endpoint in the Glassworks API Explorer.
  2. Click Callbacks.
    callbacks in the Glassworks Webhook > createWebhook > Callback page
  3. Click a callback to expand or collapse the list. (Currently, you cannot expand or collapse a single callback in the API Explorer; click to expand all or collapse all.)
  4. View the required request body for the callback.
    callbacks in the Glassworks Webhook > createWebhook > Callback page

Registration requirements

These change based on the event. Some events include requirements not listed here (i.e., commentId for listening for comment updates).

  • companyId - Call findCompany and get the id (NOT address.id or ownerId) from the response.
    • You can instead provide the documentId of a document owned by the company, and the companyId will be inferred.
    • If registered for a companyId, the event is registered for all present and future documents owned by the company.
    • onshape.document.lifecycle.statechange requires documentId instead of companyId.
    • onshape.user.lifecycle.updateappsettings requires clientId instead of companyId. See Onshape Help: Managing OAuth Applications; obtain the OAuth client identifier from the app’s Keys and secret tab.
  • events - Must be set to one of the supported event types.
  • options.collapseEvents - true or false
  • url - Must be provided to receive the webhook notifications
  • documentState - Required for onshape.document.lifecycle.statechange only. Must be one of:
    • ACTIVE - Document is in a normal, usable state.
    • TRASH - Document has been moved to the trash; user can move document back to ACTIVE state.
    • DELETED - Document has been deleted; user cannot access document.
{
  "companyId": "000000000000000000000000",
  "events": [
    "onshape.document.lifecycle.created"
  ],
  "options": {
    "collapseEvents": false
  },
  "url": "https://sampleUrl.org"
}

Webhook events

Use these events to monitor webhook changes. You do not need to register for these events; they are sent automatically when a webhook for another event type is registered, unregistered, or pinged.

  • webhook.register - Occurs in response to a notification registration API call
  • webhook.unregister - Occurs in response to a notification deregistration API call
  • webhook.ping - Occurs either:
    • In response to a request by an application to call the pingWebhook endpoint.
    • As a post-registration validation initiated by Onshape

Example Notifications

Replace the "000000000000000000000000" strings with your IDs.

webhook.register

{
  "timestamp": "2024-05-05T23:45:10.611-0500",
  "event": "webhook.register",
  "workspaceId": "000000000000000000000000",
  "elementId": "000000000000000000000000",
  "webhookId": "000000000000000000000000",
  "messageId": "000000000000000000000000",
  "data": "Some data",
  "documentId": "000000000000000000000000",
  "versionId":  "000000000000000000000000"
}

webhook.ping

{
  "timestamp": "2024-05-05T23:45:10.611-0500",
  "event": "webhook.ping",
  "workspaceId": "000000000000000000000000",
  "elementId": "000000000000000000000000",
  "webhookId": "000000000000000000000000",
  "messageId": "000000000000000000000000",
  "data": "Some data",
  "documentId": "000000000000000000000000",
  "versionId":  "000000000000000000000000"
}

onshape.model.lifecycle.changed

{
  "timestamp": "2024-05-05T23:46:29.284-0500",
  "event": "onshape.model.lifecycle.changed",
  "workspaceId": "000000000000000000000000",
  "elementId": "000000000000000000000000",
  "webhookId": "000000000000000000000000",
  "messageId": "000000000000000000000000",
  "data": "Some data",
  "documentId": "000000000000000000000000",
  "versionId":  "000000000000000000000000"
}

onshape.document.lifecycle.statechange

{
  "timestamp": "2024-05-05T23:46:29.284-0500",
  "event": "onshape.document.lifecycle.statechange",
  "workspaceId": "000000000000000000000000",
  "elementId": "000000000000000000000000",
  "webhookId": "000000000000000000000000",
  "messageId": "000000000000000000000000",
  "data": "Some data",
  "documentId": "000000000000000000000000",
  "versionId":  "000000000000000000000000",
  "documentState": "TRASH"
}

onshape.user.lifecycle.updateappsettings

{
  "timestamp": "2024-05-05T23:46:29.284-0500",
  "event": "onshape.user.lifecycle.updateappsettings",
  "workspaceId": "000000000000000000000000",
  "elementId": "000000000000000000000000",
  "webhookId": "000000000000000000000000",
  "messageId": "000000000000000000000000",
  "data": "Some data",
  "userId": "000000000000000000000000",
  "clientId":"000000000000000000000000"
}

onshape.model.translation.complete

{
  "timestamp": "2024-05-05T23:46:29.284-0500",
  "event": "onshape.model.translation.complete",
  "workspaceId": "000000000000000000000000",
  "elementId": "000000000000000000000000",
  "webhookId": "000000000000000000000000",
  "messageId": "000000000000000000000000",
  "data": "Some data",
  "documentId": "000000000000000000000000",
  "userId": "000000000000000000000000",
  "translationId": "000000000000000000000000"
}

onshape.comment.create

{
  "timestamp": "2024-05-05T23:46:29.284-0500",
  "event": "onshape.comment.create",
  "workspaceId": "000000000000000000000000",
  "elementId": "000000000000000000000000",
  "webhookId": "000000000000000000000000",
  "messageId": "000000000000000000000000",
  "documentId": "000000000000000000000000",
  "commentId": "000000000000000000000000"
}

Endpoints

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.

  • Webhook/getWebhooks
      curl -X 'GET' \
    'https://cad.onshape.com/api/v6/webhooks?user={uid}&offset=0&limit=20' \
    -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
    -H 'Authorization: Basic CREDENTIALS'
  • Webhook/createWebhook
      curl -X 'POST' \
    'https://cad.onshape.com/api/v6/webhooks' \
    -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
    -H 'Authorization: Basic CREDENTIALS' \
    -H 'Content-Type: application/json;charset=UTF-8; qs=0.09' \
    -d '{ 
          "events": [
            "eventType" // See the [Events](#events) section above for valid event types.
          ],
          "options": {
            "collapseEvents": true | false
          },
          "url": "https://sampleUrl.org"

          //Other parameters may be required. See the [Events](#events) section above.

        }'
  • Webhook/getWebhook
    curl -X 'GET' \
  'https://cad.onshape.com/api/v6/webhooks/webhookId' \
  -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Authorization: Basic CREDENTIALS'
  • Webhook/updateWebhook
      curl -X 'POST' \
    'https://cad.onshape.com/api/v6/webhooks/webhookId' \
    -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
    -H 'Authorization: Basic CREDENTIALS' \
    -H 'Content-Type: application/json;charset=UTF-8; qs=0.09' \
    -d '{
          "id": "webhookId",
          "options": {
            "collapseEvents": true | false
          }
        }'
    • Note that the webhook id must be sent in both the URL and the request body.
  • Webhook/unregisterWebhook
      curl -X 'DELETE' \
    'https://cad.onshape.com/api/v6/webhooks/{webhookId}?blockNotification=false' \
    -H 'accept: application/json;charset=UTF-8; qs=0.09' \
    -H 'Authorization: Basic CREDENTIALS'
  • Webhook/pingWebhook
      curl -X 'POST' \
    'https://cad.onshape.com/api/v6/webhooks/{webhookId}/ping' \
    -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
    -H 'Authorization: Basic CREDENTIALS'

Sample Workflows

ℹ️ NOTES

  • This page provides sample code as curl commands.
  • Replace 000000000000000000000000 strings with your IDs.

Create a webhook

An application registers for event notification by:

  1. Making a REST call to the Onshape web service
  2. Providing a URL to notify
  3. Providing the required parameters for the event types to be registered

If the registration request is well-formed, the registration API call returns information about the registration, including a unique id string that identifies the webhook registration. This corresponds to the webhookId field in other endpoints. No de-duplication of notification registrations is performed by the API. Each registration call will yield a new registrationId, 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 an asynchronous trial notification call to the URL generated from the URL template with an event type of webhook.register to test if 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 the response is received and processed by the application, so the notification handler should be ready to process notifications before the registration call is made.

In this example, we use a webhook to send information from Onshape to another server. You need a URL for Onshape to send notifications to, and a way to view the messages sent with those notifications.

  1. Open an Onshape document, or create a new one.
  2. In this example, we want to receive a notification from Onshape any time a new version is created in the specified document. For this, we’ll use onshape.model.lifecycle.createversion as our event.
  3. The event type requires one parameter. We’ll use our documentId for this field (shown as 000000000000000000000000 in the example below).
  4. All event types require specifying true or false for the options.collapseEvents field. In this case, set the field to false.
  5. Next, we need the URL to send the notification to. You must provide your own URL to receive notifications here.
  6. Confirm your createWebhook call looks like this (substitute your own authorization credentials, document ID, and URL), then make the call.
  curl -X 'POST' \
    'https://cad.onshape.com/api/v6/webhooks' \
    -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
    -H 'Authorization: Basic CREDENTIALS' \
    -H 'Content-Type: application/json;charset=UTF-8; qs=0.09' \
    -d '{
        "documentId": "000000000000000000000000",
        "events": [
          "onshape.model.lifecycle.createversion"
        ],
        "options": {
          "collapseEvents": false
        },
        "url": "https://sampleUrl.org"
    }'
  1. In your application, confirm that you received the webhook.register event from Onshape.
  2. In Onshape, create a new version in your document.
  3. In your application, confirm that you received the onshape.model.lifecycle.createversion event from Onshape. Make note of the id in the response; use this as your webhookId in subsequent examples.

Get webhook info

  1. Complete the Create a webhook steps above to obtain a webhookId.
  2. Create your getWebhook call. substitute your own authorization credentials and webhookId (shown as 000000000000000000000000 in the example below), then make the call.
  curl -X 'GET' \
    'https://cad.onshape.com/api/v6/webhooks/000000000000000000000000' \
    -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
    -H 'Authorization: Basic CREDENTIALS' \
  1. Confirm that the event in the response is onshape.model.lifecycle.createversion.

Update a webhook

  1. Complete the Create a webhook steps above to obtain a webhookId. Note that in the same response, the webhook description is null.
  2. Create your updateWebhook call. In this example, ww update the webhook’s description. Substitute your own authorization credentials and webhookId (shown as 000000000000000000000000 in the example below in both the URL and request body). Then make the call.
  curl -X 'POST' \
    'https://cad.onshape.com/api/v6/webhooks/000000000000000000000000' \
    -H 'accept: application/json;charset=UTF-8; qs=0.09' \
    -H 'Authorization: Basic CREDENTIALS' \
    -H 'Content-Type: application/json;charset=UTF-8; qs=0.09' \
    -d '{
          "id": "000000000000000000000000",
          "description": "Send a notification each time a document version is created.",
          "options": {
            "collapseEvents": false
          }
      }'
  1. Confirm in the response that the webhook description is set to Send a notification each time a document version is created.

Delete a webhook

When an application no longer needs to be notified of changes specified by a particular notification registration, it should normally deregister the notification request. Deregistration 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 that the deregistration is complete. If the application does not deregister the webhook, Onshape will continue delivering notifications until the the application either returns an error in response to a notification for the webhook or fails to respond at all for an extended period of time.

  1. Complete the Create a webhook steps above to obtain a webhookId.
  2. Create your deleteWebhook call. substitute your own authorization credentials and webhookId (shown as 000000000000000000000000 in the example below), then make the call.
  curl -X 'DELETE' \
    'https://cad.onshape.com/api/v6/webhooks/000000000000000000000000' \
    -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
    -H 'Authorization: Basic CREDENTIALS=' \
  1. In your application, confirm that you received the webhook.unregister event from Onshape.
  2. In Onshape, create a new version in your document.
  3. In your application, confirm that no new events have been received.

Additional Resources