Configure Webhooks

Overview

Walnut webhooks let you send structured session data to another system automatically whenever a tracked event occurs.

Instead of polling Walnut for updates, your configured endpoint receives an HTTP POST request when a supported event is ready. This makes it easier to trigger automations, enrich records in external systems, and move Walnut engagement data into your analytics stack in near real time.

In This Guide:

This guide walks through how to configure Walnut webhooks, receive and verify webhook events, and understand the JSON objects Walnut sends for both demo and playlist sessions.

Before You Start

Before setting up webhooks, make sure you have the right access and understand when Walnut sends session events.

Configure Webhooks

Walnut makes it easy to create a webhook, add signature verification, and send a test event before going live.

How to Configure and Test a Webhook

1. Navigate to Settings > Webhooks and click New webhook.

   

2. Enter your webhook endpoint URL and click Save.

   

3. Optionally add signature verification so your endpoint can confirm requests came from Walnut.

4. Click Send a test event to validate the connection.

   

Walnut Engagement Data at a Glance

In addition to built-in Walnut Insights, Walnut can send structured session data through webhooks so you can use it in external systems and custom workflows.

These webhook payloads can help you:

• Analyze engagement behavior and drop-off points
• Trigger automations in CRM, MAP, or internal systems
• Enrich contact, account, or opportunity records
• Power custom dashboards and downstream reporting

Use these JSON objects when building webhook handlers, integrations, enrichment flows, or custom reporting pipelines.

Demo Session Object

The demo session webhook object captures engagement with a single Walnut demo.

Walnut sends this object with the demo_session_finished event once the session data and calculated metrics are available.

Demo Session Data Points

Demo Session JSON Webhook Payload:

{
  "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": "Mozilla/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"
}

Playlist Session Object

The playlist session webhook object captures engagement with a Walnut playlist.

Because playlists can include multiple asset types, this object contains both playlist-level information and an array of individual playlist items that were available in the experience.

Playlist Session Data Points

Playlist Session JSON Webhook Payload:

{
  "data": {
    "items": [
      {
        "demo_id": null,
        "description": "An introductory demo to meet Crunchy AI and explore its core value.",
        "duration_secs": 123,
        "file_url": "https://example.com/assets/meet_crunchy_ai.mp4",
        "id": "item_1",
        "name": "Meet Crunchy AI",
        "number_of_views": 403,
        "position": 1,
        "screenshot_uri": "https://example.com/screenshots/meet_crunchy_ai.png",
        "selected": true,
        "type": "video",
        "visited": true
      },
      {
        "demo_id": null,
        "description": "A short intro deck overviewing Crunchy AI’s main features and benefits.",
        "duration_secs": 144,
        "file_url": "https://example.com/assets/intro_deck.pdf",
        "id": "item_2",
        "name": "Crunchy AI Intro Deck",
        "number_of_views": 121,
        "position": 2,
        "screenshot_uri": "https://example.com/screenshots/intro_deck.png",
        "selected": false,
        "type": "pdf",
        "visited": true
      },
      {
        "demo_id": "demo_id1",
        "description": "A demo showing how Crunchy AI unlocks smarter workflows and automation.",
        "duration_secs": 160,
        "file_url": "https://example.com/assets/smarter_workflows.mp4",
        "id": "item_3",
        "name": "Crack Open Smarter Workflows | Crunchy AI",
        "number_of_views": 90,
        "position": 3,
        "screenshot_uri": "https://example.com/screenshots/smarter_workflows.png",
        "selected": false,
        "type": "video",
        "visited": true
      },
      {
        "demo_id": "demo_id2",
        "description": "An overview of Crunchy AI’s integrations and how they connect across platforms.",
        "duration_secs": 158,
        "file_url": "https://example.com/assets/integrations.mp4",
        "id": "item_4",
        "name": "Crunchy AI Integrations",
        "number_of_views": 54,
        "position": 4,
        "screenshot_uri": "https://example.com/screenshots/integrations.png",
        "selected": false,
        "type": "video",
        "visited": true
      }
    ],
    "playlist": {
      "description": "This playlist walks through Crunchy AI’s introduction, core features, workflows, and integrations.",
      "id": "9dad64b8-ff58-4874-ae5d-020d356c514c",
      "name": "Crunchy AI Overview Playlist",
      "url": "https://app.teamwalnut.com/player/playlist?playlistId=9dad64b8-ff58-4874-ae5d-020d356c514c"
    },
    "session_duration_secs": 310,
    "session_ended": "2024-10-07T15:31:30.606000Z",
    "session_id": "80804ad4-6422-4f77-8667-7ae6aa05edad",
    "session_started": "2024-10-07T15:26:20.606000Z",
    "user": {
      "domain": "treebase.io",
      "email": "shellvis.sil@treebase.io",
      "identification_method": "email_gate",
      "ip": "123.213.123.43",
      "type": "external",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.121 Safari/537.36"
    }
  },
  "event": "playlist_session_finished",
  "is_test": true,
  "timestamp": "2025-07-11T13:19:39.526213Z"
}

Receive Webhooks

When a configured event occurs, Walnut sends an HTTP POST request to the endpoint you specified when creating the webhook.

• The request body is sent as JSON with content type application/json.
• Your endpoint should return HTTP 200 or HTTP 201 within 30 seconds.
• If your endpoint is public, it is possible for other requests to reach it, so signature verification is strongly recommended.

Verify Webhooks

To confirm that a webhook request originated from Walnut, verify the X-Walnut-Signature header using your shared secret key.

To verify a webhook:

1. Take the raw request body exactly as received.
2. Hash it using HMAC-SHA256 with your shared key.
3. Encode the result in lowercase hexadecimal format.
4. Compare that value to the X-Walnut-Signature header.

Example in Express.js:

app.post('/webhook', (req, res) => {
  const hmac = crypto.createHmac('sha256', process.env.WEBHOOK_KEY);
  hmac.update(req.rawBody);

  const calculatedSignature = hmac.digest('hex');
  const headerSignature = req.headers['x-walnut-signature'];

  if (calculatedSignature === headerSignature) {
    console.log('Signature is valid');
    res.status(200).send({ ok: true });
  } else {
    throw new Error('Signature invalid');
  }
});

Endpoint Errors and Retries

If your endpoint times out, returns a response other than 200 or 201, or fails for another reason, Walnut retries the webhook up to 3 times using exponential backoff.

Because each event retries independently, webhook deliveries can arrive out of order.

Modify, Reset, or Disable Webhooks

After a webhook is created, you can edit its configuration, test the connection again, reset the signing key, or disable the webhook entirely.

Modify, Edit, or Delete a Webhook

1. Navigate to Settings > Webhooks and open the three-dot menu.

   

2. Click Edit to update the webhook configuration.
3. Click Test connection to re-test the endpoint.
4. Click Delete to remove the webhook.

Reset Key

Reset the signing key if you suspect the current key has been compromised or if you are rotating secrets as part of your security process.

1. Navigate to Settings > Webhooks.
2. Click Reset key.
3. Walnut generates a new key for signing webhook requests.
4. Update your receiving endpoint to use the new key immediately.

Disable a Webhook

1. Navigate to Settings > Webhooks.
2. Set the webhook toggle to Off.

Summary