Skip to content

Webhook API

Webhook

Add a webhook

Url: PUT /webhook/

Permissions: write_webhook

Body

Name Type Description
event String

Kind of event the webhook should react to.
Possible values are:
- file_uploaded: Triggered when a file is uploaded or when a new revision of a file is uploaded. The data field contains the file stored in the database.
- file_optimized: Triggered when a file has been optimized. The data field contains the file stored in the database.
- attribute_updated: Triggered when an attribute has been added or updated. In the data field, user is the user who has created/updated the attribute and nodeIdToAttributes is a mapping between each node id and the attributes that have been updated.
- annotation_created: Triggered when an annotation has been created. The data field contains the newly created annotation.
- annotation_updated: Triggered when an annotation has been updated. The data field contains the old annotation and the new annotation.
- annotation_removed: Triggered when an annotation has been removed. The data field contains the removed annotation.
- configuration_created: Triggered when a configuration is created. The data field contains the newly crated configuration.
- configuration_updated: Triggered when a configuration has been updated. The data field contains the old configuration and the new configuration.
- configuration_removed: Triggered when a configuration has been removed. The data field contains the removed configuration.

url String

URL that will be called when the Webhook is triggered

secretToken String

Secret token that will be sent with each hook request in the X-Smartshape-Token HTTP header.
Your webhook endpoint can check that to verify that the request is legitimate.
The secretToken is hashed using the bcrypt algorithm which has implementations for most major languages

Success-Response:
HTTP/1.1 200 OK
{
  "data":{
     "type":"webhook",
     "attributes": {
       "__v": 0,
       "_id": "5c6fbb654fb090280ecc926b",
       "event": "attribute_updated",
       "url": "https://www.example.com/webhook/",
       "secretToken": "$2a$10$YB7R3ubW/LWCCmS6XtF/Z.8J.f3nmR96ZOD0kKphMlA5ndc2yiBhy",
       "owner": "280ecc926b5c6fbb654fb090"
     }
   }
 }

Error 4xx

Name Type Description
400

Missing argument

503

Unauthorized

Error-Response:
HTTP/1.1 503 Unauthorized
{
  "errors": [
      {
        "status": 400,
        "title": "Webhook already exists",
        "detail":"This webhook already exists",
        "code":"WEBHOOK_ALREADY_EXISTS"
      }
   ]
 }
annotation_updated webhook payload example:
{
    file: '5c6aeed079bf3f432d3c929e',
    event: 'annotation_updated',
    data:
    {
        old:
        {
            targets: [],
            tags: [],
            readPermissions: [],
            writePermissions: [],
            permissions: [Object],
            __v: 0,
            author: 'test@smartshape.io',
            file: '5c6aeed079bf3f432d3c929e',
            lastUpdate: 1550826341717,
            date: 1550826341717,
            type: 0,
            content: 'DESCRIPTION',
            color: '#fff',
            cameraZ: 3.394551,
            cameraY: 1.988481,
            cameraX: 3.394551,
            name: 'test1',
            _id: '5c6fbb654fb090280ecc926b'
        },
        new:
        {
            targets: [],
            tags: [],
            readPermissions: [],
            writePermissions: [],
            permissions: [Object],
            __v: 0,
            author: 'test@smartshape.io',
            file: '5c6aeed079bf3f432d3c929e',
            lastUpdate: 1550826341717,
            date: 1550826341717,
            type: 0,
            content: 'DESCRIPTION',
            color: '#fff',
            cameraZ: 3.394551,
            cameraY: 1.988481,
            cameraX: 3.394551,
            name: 'TITLE3',
            _id: '5c6fbb654fb090280ecc926b'
        }
    },
    owner: 'test@smartshape.io',
    runTimestamp: 1550826412941,
    uuid: 'a90c85c3-fa3e-4a88-be6f-8c1270c4c27b'
}
Example usage:
curl -X PUT 'https://smartshape.io/webhook/' \
     -H 'Authorization: Bearer <auth_token>' \
     -H 'X-SmartShape-Session: <session_token>' \
     -H 'Content-Type: application/json' \
     -d '{ 
             "event": "attribute_updated", 
             "url": "https://www.example.com/webhook/", 
             "secretToken": "[SECRET_TOKEN]" 
         }'

Delete a webhook

Url: DELETE /webhook/:webhook/

Permissions: write_webhook

Parameter

Name Type Description
webhook String

Webhook id

Success 200

Name Type Description
success Boolean
Success-Response:
HTTP/1.1 200 OK
{
  "success": true
}

Error 4xx

Name Type Description
404

Not found

503

Unauthorized

Example usage:
curl -X DELETE -H 'Authorization: Bearer <auth_token>' -H 'X-SmartShape-Session: <session_token>' 'https://smartshape.io/webhook/587ca29dd564001b7cfc1196/'

List webhooks

Url: GET /webhook/

Permissions: read_webhook

Success-Response:
HTTP/1.1 200 OK
{
    "data": [
        {
            "type": "webhook",
            "id": "5988925c2dd3f45c740fdf2f",
            "attributes": {
                "event": "attribute_updated",
                "url": "https://www.example.com/webhook/",
                "secretToken": "$2a$10$HozKzQ5mDQ.haoTWDK3Nm.chd729rExtQLiTRoDtGQlWr4/Uh.2PS",
                "owner": "test@smartshape.io"
            }
        },
        {
            "type": "webhook",
            "id": "598894c09fcc9f5e28771934",
            "attributes": {
                "event": "attribute_updated",
                "url": "https://www.example.com/webhook2/",
                "secretToken": "$2a$10$mAPjVNOH1mavC/Hu5X1UxufoSxrTac0FqIBjTDEDeY1723Vyc.QTG",
                "owner": "test@smartshape.io"
            }
        }
    ]
}

Error 4xx

Name Type Description
503

Unauthorized

Example usage:
curl -X GET -H 'Authorization: Bearer <auth_token>' -H 'X-SmartShape-Session: <session_token>' 'https://smartshape.io/webhook/'

September 11, 2024 September 11, 2024