Webhooks

Webhooks provide a notification system to alert you to changes made in your project. It works as the opposite of the REST API, where you contact the Smartlook servers for information. When a webhook is triggered, the Smartlook servers contact you to alert you of the change, pushing the data to you.

Why use webhooks?

Webhooks offer you a variety of benefits. A major benefit of Webhooks is that you receive the information in real time. When a user completes an action that triggers a webhook, you receive notification of that action. This also increases your efficiency, allowing you to wait for the information to come to you rather than searching for it on your own.

Setting up webhooks

To set up webhooks:

Set the body parameters:
- url — The client URL that listens for webhooks
- type — The type of webhook. Currently, you can have a webhook for issues and notes.
- secret — Optional parameter that acts as an extra layer of security. For more information, see Setting a secret.
Send the parameters using the public-api:

POST /api/v1/webhoooks
BODY: {
  "url": "https://yourUrl.com",
  "type": "issues"|"notes",
  "secret": "your-secret" 
}

The API then sends a response with an ID:

{
  "id": "IDofWebHook"
}

Now, wait for a user to trigger your webhook.

Setting a secret

If you decide to set a secret for your webhook, Smartlook creates a hash signature that is attached to each payload in the header Smartlook-Signature-256.

Hash verification

The hash-based message authentication codes (HMAC) uses the SHA256 hashing function and is digested as a HEX string. An example of the function:

const crypto = require('crypto')

const secret = SECRET_TOKEN
const message = request.body

const signature = crypto
        .createHmac('sha256', secret)
        .update(`${message}`)
        .digest('hex')

How users trigger webhooks

Currently, you can create webhooks for issues and notes. A user can access these by clicking the Sharing and notes button in the session controls. When a user triggers a webhook, the response is sent as JSON in a POST HTTP request to the URL you set in the parameters.

Issues webhooks

Users trigger your issues webhook when they click the Send to Jira or Send to Slack buttons.

Example response of an issues webhook:

{
    "type": "issue.created",
    "timestamp": "2022-11-08T14:46:50.770Z",
    "project": {
        "id": "697d3b6583d54c95acb2c34e3fb5",
        "name": "Project Name"
    },
    "organization": {
        "id": "028b773725fe43e48c6b8d78bb8b",
        "name": "Organization Name"
    },
    "data": {
        "author": {
            "name": "Author Name",
            "email": "[email protected]"
        },
        "visitor": {
            "id": "bc54d883a80b4625a"
        },
        "session": {
            "id": "555648dc9bf34431b2dae4872d"
        },
        "summary": "Bug Report",
        "text": "BUG REPORT \r\n\r\nBrowser: Chrome 104.0.0.0\r\nOperation system:OS X\r\nBrowser type: desktop\r\nDimensions: 2560x1440\r\nTime of recording: Sep 02, 2022 1:08 PM\r\nUser ID: 926e5abe46d24212b51722f5539b3938\r\nLocation: Brno\r\n",
        "shareUrl": "https://app.smartlook.com/play/shared/e9478e6644a843acb9e2bda2b11ccdd2",
        "time": 72,
        "createdAt": "2022-11-08T14:46:48.519Z"
    }
}

Notes webhooks

Users trigger your notes webhook when they enter a note in the notes area and click Save note.

Notes webhooks also have an added comments webhook that a user triggers if they respond to a note.

Example response of a notes webhook:

{
    "type": "note.created",
    "timestamp": "2022-11-29T13:25:43.385Z",
    "project": {
        "id": "0fbf4a5b4da2486283abefdb37cc4f24",
        "name": "Project Name"
    },
    "organization": {
        "id": "cb673450a59a4f96bbae58770a9fa49e",
        "name": "Project Organisation"
    },
    "data": {
        "id": "54a52bf12",
        "author": {
            "name": "Author Name",
            "email": "[email protected]"
        },
        "noteType": "session",
        "createdAt": "2022-11-29T13:25:43.258Z",
        "updatedAt": null,
        "text": "Note Text",
        "visitor": {
            "id": "e24c8993c9c84c458"
        },
        "session": {
            "id": "c45832f7d9705834742",
            "sessionTime": 435,
            "sessionDuration": 833
        },
        "noteCommentsCount": 0
    }
}

Example response of a comments webhook:

{
    "type": "comment.created",
    "timestamp": "2022-11-29T13:26:04.127Z",
    "project": {
        "id": "0fbf4a5b4da2486283abefdb37cc4f24",
        "name": "Project Name"
    },
    "organization": {
        "id": "cb673450a59a4f96bbae58770a9fa49e",
        "name": "Organization Name"
    },
    "data": {
        "id": "74EGYgIRWf",
        "author": {
            "name": "Author Name",
            "email": "[email protected]"
        },
        "createdAt": "2022-11-29T13:26:04.018Z",
        "updatedAt": null,
        "text": "Comment Text",
        "visitor": {
            "id": "e24c8993c9c84c458"
        },
        "session": {
            "id": "c45832f7d9705834742",
            "sessionTime": 435,
            "sessionDuration": 833
        },
        "noteCommentsCount": 1,
        "noteType": "session",
        "parentNote": {
            "id": "54a52bf12",
            "author": {
                "name": "Author Name",
                "email": "[email protected]"
            },
            "createdAt": "2022-11-29T13:25:43.000Z",
            "updatedAt": null,
            "text": "Note Text"
        }
    }
}