+ + + + + + + + + + +

The following documentation is for “Webhooks v1.0” (Deprecated). A new field within the input object - version - allows a user to opt into selecting the version of webhooks that they would like to use.

+ +
mutation registerWebhookCallback {
+  addModelEventWebhookCallback (input: {
+    eventTypes: [inserted, deleted, updated],
+    callback: {
+      scheme: "https",
+      host: "myawesomeapi.com",
+      path: "my/api/path"
+      queryParams: [
+        {
+          key: "key1",
+          value: "value1"
+        },
+        {
+          key: "key2",
+          value: "value2"
+        }
+      ]
+      credType: basic
+      credKey: "username"
+      credSecret: "password"
+    } 
+  }) {
+    id
+    eventTypes
+    callback{
+      scheme
+      host
+      path
+      queryParams {
+        key
+        value
+      }
+    }
+  }
+}
+
+ +

Webhooks v2.0 expands upon the available events and provides detailed information in the returned payload as to what fields or status have changed. We highly recommend migrating your application.

+ +
+ +

Getting Started

+ +

The ability to register Webhook callbacks with the Matterport system requires:

+ +
    +
  • Account Feature Unlock
    • +
  • Developer License Unlock and API Tokens
    • +
  • Enterprise Subscription Plan
    • +
+ +

Once enabled, Webhook callbacks can be registered and managed through the our Model API.

+ +

Webhook Events

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventDescription
uploadedAn event will be emitted when a model is uploaded for the organization
processedAn event will be emitted when a model has completed processing
insertedAn event will be emitted when a model is insert into the database, which typically coincides with an uploaded event.
updatedAn event will be emitted when a model is updated
deletedAn event will be emitted when a model is deleted
bundle_requestedAn event will be emitted when an Add-On (bundle) is requested for a model
bundle_completedAn event will be emitted when an Add-On (bundle) is completed
+ +

Sample Events

+ +
+ uploaded + + 
{
+  "type": "uploaded",
+  "modelId": "FR1wedSZUWQ",
+  "timestamp": 1663595798725,
+  "internalId": "internal id",
+  "createdBy": "test@test.com",
+  "data": {}
+}
+
+ +
+
+ processed + + 
{
+  "type": "processed",
+  "modelId": "MXepojQAL2p",
+  "timestamp": 1663595796940,
+  "internalId": "internal id",
+  "createdBy": "test@test.com",
+  "data": {
+    "success": "true"
+  }
+}
+
+ +
+
+ inserted + + 
{
+  "type": "inserted",
+  "modelId": "PFiuXnwfE4h",
+  "timestamp": 1663596098947,
+  "internalId": "internal id",
+  "createdBy": "test@test.com",
+  "data": {}
+}
+
+ +
+
+ deleted + + 
{
+   "type":"deleted",
+   "modelId":"zs1BKwZKQrc",
+   "timestamp":1663596098948,
+   "internalId":"internal id",
+   "createdBy":"test@test.com",
+   "data":{ 
+   }
+}
+
+
+
+ bundle_requested + + 
{
+   "timestamp":1663596098949,
+   "modelId":"GvuipKBo1N1",
+   "internalId":"internal id",
+   "bundleId":"bim:cad",
+   "bundleOptions":{
+      "style":"mep"
+   },
+   "orderedBy":"test@test.com",
+   "type":"bundle_requested"
+}
+
+
+
+ bundle_completed + + 
{
+   "timestamp":1663596098961,
+   "modelId":"rbEVEory2uo",
+   "internalId":"internal id",
+   "bundleId":"bim:cad",
+   "bundleOptions":{
+      "style":"mep"
+   },
+   "orderedBy":"test@test.com",
+   "success":true,
+   "type":"bundle_completed"
+}
+
+
+ +

Model Events

+ +

Model Event Call Payload

+ +

The Webhook payload will contain information on the event that occurred.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescriptionExample Value
typeThe type of registered event that occurred.updated
modelIdID of the affected modelj4RZx7ZGM6T
timestampUnix timestamp of the event1657580633950
event Webhook:Event.Callback
+ +

Registering a Model Event Callback

+ +

Webhook callback registration and management for model events is handled through various mutations to the Model API.

+ +

The addModelEventWebhookCallback mutation registers a callback URL through a WebhookCallbackInput object for specified eventTypes. Optional query parameters can be included, as well as basic or token credentials for authentication.

+ +

For security reasons, it’s recommended to provide credentials for the Webhook callback registration.

+ +
+ addModelEventWebhookCallback + + 
mutation registerWebhookCallback {
+  addModelEventWebhookCallback (input: {
+    eventTypes: [inserted, deleted, updated],
+    callback: {
+      scheme: "https",
+      host: "myawesomeapi.com",
+      path: "my/api/path"
+      queryParams: [
+        {
+          key: "key1",
+          value: "value1"
+        },
+        {
+          key: "key2",
+          value: "value2"
+        }
+      ]
+      credType: basic
+      credKey: "username"
+      credSecret: "password"
+    } 
+  }) {
+    id
+    eventTypes
+    callback{
+      scheme
+      host
+      path
+      queryParams {
+        key
+        value
+      }
+    }
+  }
+}
+
+ +

Sample Response:

+ + 
{
+  "data": {
+    "addModelEventWebhookCallback": {
+      "id": "887n9rwrdxytnttms0t1h02mc",
+      "eventTypes": [
+        "inserted",
+        "updated",
+        "deleted"
+      ],
+      "callback": {
+        "scheme": "https",
+        "host": "myawesomeapi.com",
+        "path": "my/api/path"
+        "queryParams": [
+          {
+            "key": "key1",
+            "value": "value1"
+          },
+          {
+            "key": "key2",
+            "value": "value2"
+          }
+        ]
+      }
+    }
+  }
+}
+
+ +

Try this query in our interactive console

+ +
+ +

List Registered Model Event Callbacks

+ +

A list of registered Model Event callbacks can be acquired through the modelEventWebhookCallbacks query search. Like other search operations, results are paginated and can be iterated though by specifying the returned offset value for the next page.

+ +
+ modelEventWebhookCallbacks + + 
query getModelEventCallbacks {
+  modelEventWebhookCallbacks {
+    nextOffset
+    totalResults
+    results {
+      id
+      eventTypes
+      callback {
+        scheme
+        port
+        path
+      }
+    }
+  }
+}
+
+ +

Sample Response:

+ +

(Note the ids, as these will be used in the mutation to make any changes to the registered callback.)

+ + 
{
+  "data": {
+    "modelEventWebhookCallbacks": {
+      "totalResults": 1,
+      "results": [
+        {
+          "id": "887n9rwrdxytnttms0t1h02mc",
+          "eventTypes": ["inserted", "updated", "deleted"],
+          "callback": {
+            "scheme": "https",
+            "port": 80,
+            "path": "myawesomeapi.com"
+          }
+        }
+      ]
+    }
+  }
+}
+
+ +

Try this query in our interactive console

+ +
+ +

Update a Model Event Callback

+ +

Once the callback id is received, the patchModelEventWebhookCallback mutation can be used to make updates to an already-registered callback.

+ +
+ patchModelEventWebhookCallback + + 
mutation updateModelEventCallback($callbackId: ID!) {
+  patchModelEventWebhookCallback(
+    id: $callbackId
+    input: {
+      callback: {
+        scheme: "https"
+        host: "myawesomeapi.com"
+        path: "v2/my/api/path"
+        queryParams: [
+          { key: "key1", value: "value1" }
+          { key: "key2", value: "value2" }
+        ]
+        credType: basic
+        credKey: "username"
+        credSecret: "password"
+      }
+    }
+  ) {
+    id
+    eventTypes
+    callback {
+      scheme
+      host
+      path
+    }
+  }
+}
+
+ +

Sample Response:

+ + 
{
+  "data": {
+    "patchModelEventWebhookCallback": {
+      "id": "887n9rwrdxytnttms0t1h02mc",
+      "eventTypes": ["inserted", "updated", "deleted"],
+      "callback": {
+        "scheme": "https",
+        "host": "myawesomeapi.com",
+        "path": "v2/my/api/path"
+      }
+    }
+  }
+}
+
+ +

Try this query in our interactive console

+ +
+ +

Remove a Model Event Callback

+ +

Model Event Callbacks can be removed using the removeModelEventWebhookCallback mutation.

+ +
+ removeModelEventWebhookCallback + + 
mutation removeModelEventCallback($callbackId: ID!) {
+  removeModelEventWebhookCallback(id: $callbackId)
+}
+
+ +

Sample Response:

+ + 
{
+  "data": {
+    "removeModelEventWebhookCallback": true
+  }
+}
+
+ +

Try this query in our interactive console

+ +
+ +

Testing Model Event Callbacks

+ +

Tests for specific Model Events can be triggered using the pingModelEventWebhookCallback mutation. The mutation can be used to ping and event that would trigger the registered callback. A collection of mutations and queries used for testing a Webhook endpoint can be found at this interactive editor link.

+ +

Ngrok is one useful tool for testing a Webhook integration locally.

+ +
+ pingModelEventWebhookCallback + + 
mutation testModelEvent($callbackId: ID!) {
+  pingModelEventWebhookCallback(id: $callbackId)
+}
+
+ +

Try this query in our interactive console

+ +
+ +

Model Event Callback FAQs

+ +
+ Can I make GET callbacks instead of POST? +

No, only POST request callbacks are supported.

+
+
+ Can I make REST Callbacks instead of GraphQL? +

Only GraphQL-based API callback registrations are available.

+
+
+ What is the error message like if id is wrong for patchModelEventWebhookCallback +

Error fetching data

+
+ + +
+ +
+ + + +