Matterport Webhooks Overview

Webhooks, sometimes referred to as “reverse APIs,” function like an API that’s triggered by events rather than requests. Matterport’s webhook framework lets you subscribe to events so that you can get real-time notifications and updates. This way, instead of your system having to repeatedly ask Matterport’s system whether an event occurred, you can set up a webhook so that you’re notified when it happens.

Currently, we offer the following events with webhook callback functionality:

• Model processing complete
• Add-on asset is available to download
• Purchase activity has occurred. This event is triggered when someone in the account places an order.
• Model upload event is completed. This event is triggered when a model has been successfully uploaded, whether or not it has been processed.

https://en.wikipedia.org/wiki/Webhook

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

Sample Events

{
  "type": "uploaded",
  "modelId": "FR1wedSZUWQ",
  "timestamp": 1663595798725,
  "internalId": "internal id",
  "createdBy": "test@test.com",
  "data": {}
}

{
  "type": "processed",
  "modelId": "MXepojQAL2p",
  "timestamp": 1663595796940,
  "internalId": "internal id",
  "createdBy": "test@test.com",
  "data": {
    "success": "true"
  }
}

{
  "type": "inserted",
  "modelId": "PFiuXnwfE4h",
  "timestamp": 1663596098947,
  "internalId": "internal id",
  "createdBy": "test@test.com",
  "data": {}
}

{
   "type":"deleted",
   "modelId":"zs1BKwZKQrc",
   "timestamp":1663596098948,
   "internalId":"internal id",
   "createdBy":"test@test.com",
   "data":{ 
   }
}

{
   "timestamp":1663596098949,
   "modelId":"GvuipKBo1N1",
   "internalId":"internal id",
   "bundleId":"bim:cad",
   "bundleOptions":{
      "style":"mep"
   },
   "orderedBy":"test@test.com",
   "type":"bundle_requested"
}

{
   "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.

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.

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
      }
    }
  }
}

{
  "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"
          }
        ]
      }
    }
  }
}

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.

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

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

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.

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
    }
  }
}

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

Remove a Model Event Callback

Model Event Callbacks can be removed using the removeModelEventWebhookCallback mutation.

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

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

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.

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

Model Event Callback FAQs