About
Webhooks are behind the scenes objects. Instead of constantly checking for updates, a webhook tells an app or service to send a message whenever something specific happens. This way, the app or service only gets the information it needs when it needs it, saving time and effort.
Before you start
- This feature is for admins.
- Every time a demo is viewed, an event will be sent to your selected endpoint.
- Walnut sends a webhook notification as soon as all the data from the payload is available. In case of demo play, which contains calculated analytical data, it can take up to two hours to receive the notification.
Configure webhooks
> To configure and test a webhook:
- Navigate to Settings>Webhooks and click New webhook. A new screen opens.
- Enter the webhook URL endpoint and click Save. If all’s good, you’ll see the success message.
- You can add a signature verification (see #2 in the image).
- Click Send a test event test to confirm the webhook works as expected. Hopefully you’ll see the success message!
Payload parameters
This is an example of the payload parameters.
{
"data": {
"demo": {
"id": "7a8e73ec-93ef-4f35-aadf-33c2ada9b887",
"name": "My Awesome Demo",
"template_id": "473e5dd0-7447-4c84-9a09-d0cd51442c0a",
"template_name": "My Awesome template",
"url": "https://app.teamwalnut.com/player/?demoId=7a8e73ec-93ef-4f35-aadf-33c2ada9b887&showGuide=true&showGuidesToolbar=true&showHotspots=true&source=unknown"
},
"demo_engagement": {
"fab_clicks": 0,
"guides_completion_rate": 15,
"last_guide_shown": null,
"last_section_viewed": null,
"screen_completion_rate": 11,
"session_duration": 4
},
"session_id": "eb8af248-a970-46fa-bfb0-cb675b6780e1",
"session_started": "2023-11-01T16:36:47.905000Z",
"user": {
"email": "someone-awesome@walnut.io",
"user_agent": "ozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36"
}
},
"event": "demo_session_finished",
"timestamp": "2023-11-01T19:15:20.666248Z"
}
Parameter attributes & types
This table lists the parameter attributes and types.
| Attribute | Description | Type |
| Demo - ID | ID of the demo. | String |
| Demo - name | Name of the demo. | UUID |
| Template - ID | ID of the template. | String |
| Template - name | Name of the template. | URL |
| URL (demo) | URL of the demo. | URL |
| FAB clicks | Number of times the Floating Action Button (FAB) was clicked. | Integer |
| Guides completion rate | Represents the percentage of total guides completed., in %. | Integer |
| Last guide shown | Last guide the user has seen in the demo session. | String |
| Last section viewed | Last section the user has seen in the demo session. | String |
| Screen completion rate | The completion rate of the screens in the demo, in %. | Integer |
| Session duration | The total duration of the session. | Integer |
| Session ID | A unique identifier for the session. | UUID |
| Session started | Timestamp indicating when the session started. | Datetime |
| User email | If it exists, the email of the demo viewer. | |
| User agent | The browser’s user agent. | String |
| Event | Name of the event. | String |
| timestamp | Timestamp indicating when the session started. | Datetime |
Receive webhooks
You receive HTTP POST requests on the endpoint you specified when you created the webhook.
- The requests contain a JSON body with the event payload and their content type will be set to application/json.
- Your endpoint should respond with HTTP status 200 or 201 in a timely manner (under 30 seconds), otherwise Walnut considers that is not working and might not deliver the requests.
- Because the endpoint on which you will receive requests must be publicly available, it is possible that someone will find it and try to send something that imitates Walnut webhook events to it.
- To make sure the events originated from Walnut, you may perform a verification procedure, for which you will need a shared key that was created for you when you set up the webhook.
- Verify webhooks
> To perform a verification:
- Take the raw body of the webhook request
- Hash it with HMAC-SHA256, using the shared key from Walnut.
- Encode it using base16, make sure the results are lowercase.
- Compare the results with the contents of X-Walnut-Signature header from the request.
Sample code
The example code in Express.js might look similar to this:
app.post('/webhook', (req, res) => {
let hmac = crypto.createHmac('sha256', process.env.WEBHOOK_KEY);
hmac.update(req.rawBody);
const calculatedSignature = hmac.digest('hex').toString('base16');
const headerSignature = req.headers['x-walnut-signature']
if (calculatedSignature == headerSignature) {
console.log('Signature is valid');
res.send({ok: true});
} else {
throw new Error('Signature invalid');
}
})
- Endpoint errors
When your endpoint returns a response other than 200 or 201, times out or fails for any other reason, Walnut sends the webhook 3 times with an exponential backoff.
This might result in webhook events arriving out of order, as each event has its own retrying strategy.
In such cases, test the connection to make sure the webhook has the correct configuration.
Modify, edit or delete webhooks
> To modify, edit or delete a webhook:
- Navigate to Settings>Webhooks and open the 3 dots dropdown.
- Click Edit to open the webhook and modify it.
- Click Test connection to test it or Delete to delete it.
Reset key
Use Reset key if you suspect that your key to sign webhook payloads is compromised or you want to perform a secret rotation.
< To create / reset a key:
- Navigate to Settings>Webhooks and click Reset key.
- Walnut creates a new key using it to sign webhook requests.
- After the reset, the old key will not longer work, so please ensure that you update the receiving endpoint.
Disable webhooks
> To disable a webhook:
- Navigate to Settings>Webhooks and set the toggle to OFF.