Matterport Webhooks v1 (Deprecated)
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 inserted 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"
}
]
}
}
}
}
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"
}
}
]
}
}
}
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"
}
}
}
}
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
}
}
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)
}