Matterport Webhooks v1 (Deprecated) | Matterport Developers

Note: Webhooks are only available for Enterprise-level Matterport Subscriptions

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

Event	Description
uploaded	An event will be emitted when a model is uploaded for the organization
processed	An event will be emitted when a model has completed processing
inserted	An event will be emitted when a model is insert into the database, which typically coincides with an uploaded event.
updated	An event will be emitted when a model is updated
deleted	An event will be emitted when a model is deleted
bundle_requested	An event will be emitted when an Add-On (bundle) is requested for a model
bundle_completed	An 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.

Field	Description	Example Value
type	The type of registered event that occurred.	updated
modelId	ID of the affected model	j4RZx7ZGM6T
timestamp	Unix timestamp of the event	1657580633950
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