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