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.

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.

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 addWebhook {
  addModelEventWebhookCallback(
    input: {
      eventTypes: [created, deleted]
      callback: {
        scheme: "http"
        host: "myawesomeapi.com",
        port: 9090
        path: "testWebhook"
        credType: basic
        credKey: "Your API Key"
        credSecret: "Your API Secret"
        additionalHeaders: [
          { key: "key1", value: "value1" }
          { key: "key2", value: "value2" }
        ]
        queryParams: [
          { key: "key1", value: "value1" }
          { key: "key2", value: "value2" }
        ]
      }
      version: 2
    }
  ) {
    id
    eventTypes
    callback {
      scheme
      host
      port
      path
    }
    version
  }
}

{
  "data": {
    "addModelEventWebhookCallback": {
      "id": "887n9rwrdxytnttms0t1h02mc",
      "eventTypes": [
        "created",
        "deleted"
      ],
      "callback": {
         ... 
      },
      version: 2
    }
  }
}

You may use the queryParams object to define additional parameters that will be passed to your endpoint. If your endpoint requires additional headers, you may also pass them as key/value pairs.

For reference, please review the schema for this mutation.

Versions

The version field allows a user to select the version of Webhooks that they are wishing to implement. Webhooks version 2 was introduced in November 2024 and is documented on this page. For reference materials on the prior version, please visit the Webhooks v1.0 (deprecated) reference guide.

Event Types

The following events can subscribed to with WebHooks v2.0.

Webhook Callback Payload

Common attributes, all webhook events will have these properties at the root level.

Webhook Body Object

The ModelDetailsChanged payload will not be propagated until model processing completes. The events that would trigger a ModelDetailsChanged event and would be included in the previous/current payloads:

• address { * }
• description
• image { id }
• internalId
• mls { id name }
• name
• publication { description, externalUrl, presentedby, summary }

Model Processed & Activation State Changed

When a model has finished processing it may not immediately be active and ready to accept mutations.

For the majority of our users, a model will begin with a pending status. Our platform will analyze the number of scans to determine the number of active spaces that the model will consume and will check the available spaces left for your account. If the account has the capacity to store this new model, the model will then be set to active.

Performing a mutation immediately after a model has processed may result in an error. This race condition can be mitigated by subscribing to both the processed and activation_state_changed events and waiting until both the processed and active conditions have been met.

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"
      }
      version: 2
    }
  ) {
    id
    eventTypes
    callback {
      scheme
      host
      path
    }
  }
}

{
  "callbackId": "XYZ"
}

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