Webhooks

Send real-time notifications from Userpilot to your own backend or third-party tools whenever an event happens in your product.

What are webhooks?

Webhooks (sometimes called callbacks) let you build a custom, real-time integration between Userpilot and your own systems. Instead of your tools polling Userpilot for updates, Userpilot sends an HTTP POST request to an endpoint you control the moment an event happens — a flow gets completed, an NPS score comes in, someone unsubscribes from an email. Each request carries a JSON payload describing what happened and, where relevant, who it happened to.

Because delivery is immediate, webhooks are the right tool when another system needs to react to in-app behavior as it happens, not after a batch export. If you need historical or bulk event data instead, see Data Sync or the native HubSpot and Salesforce integrations.

When to use webhooks

Reach for a webhook whenever another system needs to know about something the moment it happens in Userpilot:

• Fire a scenario in an automation platform like Zapier or Workato when a user takes a specific in-app action
• Kick off an email campaign the moment a user submits a particular NPS score
• Stream flow, checklist, or survey engagement into your analytics tools for real-time analysis
• Notify your own backend when an event occurs so you can update state on your side
• Push real-time activity into a CRM such as HubSpot
• Post a notification to a Slack channel when a user takes an action in Userpilot
• Sync email unsubscribes and re-subscribes out of Userpilot and into your own email or CRM tools

Webhooks are available on Growth and Enterprise plans. To learn more about upgrading, reach out to [e-mail].

Before you start

• Plan: your account needs to be on Growth or Enterprise.
• An endpoint: a URL that can accept an HTTP POST request with a JSON body — typically an endpoint on your own backend, or a tool like Zapier or Workato. webhook.site is a convenient way to inspect payloads while you’re building.
• A plan for what to send: decide which event types you need, and whether you want all items of that type (all flows, all checklists, etc.) or only specific ones — you’ll scope this per event type when you set up the webhook.

Supported events

A single webhook can be configured to fire on one or more of the following event types. Most can be scoped to specific items and filtered to specific statuses, so you only receive the events you actually need.

Event type	Scope selector	Status filter (has been)
Feature Tags (Legacy)	Specific feature tags, or all	Hover, Click, Text Input
Tracked Events	Specific tracked events, or all	Fires whenever the event is tracked
Labeled Events	Specific labeled events, or all	Fires whenever the event occurs
Tagged Pages	Specific tagged pages, or all	Fires on page view
Checklists	Specific checklists, or all	Seen, Completed, Dismissed
Flows	Specific flows, or all	Seen, Completed, Dismissed
Mobile content	Specific mobile content, or all	Seen, Completed, Dismissed
NPS	All NPS surveys	Skipped, Submitted
Surveys	Specific surveys, or all	Seen, Submitted, Dismissed
Forms	Specific forms, or all	Submitted
Workflows	Specific workflows, or all	Enrolled, Completed
Emails	All subscription types	Unsubscribed, Re-subscribed — filterable by source (Manual, CSV import, API, Preference center, One-click unsubscribe)

Feature Tags (Legacy) is the original feature-tagging system. Going forward, Userpilot captures that kind of interaction data through Tracked Events, Labeled Events, and Tagged Pages instead — the Legacy option remains for webhooks that already depend on it.

Create a webhook

Webhooks live under Settings → Integrations → Webhooks.

1. Start a new webhook

   From the Webhooks tab, click Create Webhook. In the dialog, give it a descriptive Name and the Endpoint URL you want events sent to, then click Create.

2. Fill in the details

   Creating the webhook opens the Configure webhook panel on the Details step, with your name and endpoint already filled in. From here you can also set:

   • Secret Auth-Token — a token Userpilot includes with every request so your endpoint can confirm it really came from Userpilot. Strongly recommended; see Verify webhook signatures below.
   • Webhook Description — shown next to this webhook in your webhooks list, useful once you have more than one.
   • Send staging data only — toggle this on while you’re testing so only staging-environment events are sent, keeping production data out of your endpoint until you’re ready. The payload’s environment field reflects whichever mode is active.

   Click Next to continue.

3. Choose what to send

   On the Data setup step:

   1. Under User Properties and Company Properties, click Add to include user or company properties in every payload — up to 30 properties in total (shown as Properties: x / 30).
   2. For each event type you want to trigger the webhook, turn its toggle on, then use the Select [event type] dropdown to scope it to specific items, or leave it on All … Selected. Where a has been dropdown is available, choose which statuses should trigger the webhook — for example, only Completed for Flows rather than every Seen.
   3. For Emails, choose which statuses (Unsubscribed, Re-subscribed) and which source(s) — Manual, CSV import, API, Preference center, One-click unsubscribe — should trigger the webhook.

   An event type only fires if its toggle is switched on. Before saving, double-check that every category you care about is enabled and scoped the way you expect.

4. Test and save

   Click Send Test on either step to send a sample payload to your endpoint using your current configuration, so you can confirm your integration handles it correctly. When you’re happy with the setup, click Save.

Manage existing webhooks

The Webhooks tab lists every webhook you’ve created, with its Name, Description (shown as “Description Not Available” if you left it blank), and Status.

• Enable or disable a webhook with the Status toggle in its row — a saved webhook sends nothing while its status is off.
• Use the ⋮ menu on a row for other actions on that webhook.
• Click a webhook’s name to reopen the Configure webhook panel and adjust its details or data setup at any time.

Test webhook events

You don’t need to enable a webhook to try it. Send Test is available on both the Details and Data setup steps, and sends a sample event to your endpoint using whatever configuration you’ve entered so far — a fast way to validate your endpoint before the webhook goes live.

Test sends don’t change real data. For example, a test send for the Emails event never actually unsubscribes anyone.

---

Verify webhook signatures

To ensure the security and integrity of the events Userpilot sends to your webhook, every request includes a signature in the X-Signature header. Verifying this signature confirms the event was sent by Userpilot and hasn’t been tampered with in transit.

Structure of the X-Signature header

The X-Signature header consists of two components: t={{TIMESTAMP}},v1={{SIGNATURE}}.

• t: timestamp of the request.
• v1: signature derived from the request payload and your secret token.

How to verify the signature

To verify the signature (v1 value) of an incoming webhook event:

1. Parse the request body: extract and stringify the JSON payload of the incoming request.
2. Retrieve the timestamp: extract the timestamp value (t) from the X-Signature header. As a fallback, the timestamp is also included in the request body.
3. Construct the signature base string: concatenate the stringified request body and the timestamp with a period (.) in between: signature_base_string = stringified_request_body + "." + timestamp
4. Compute the HMAC SHA-256 signature: using your secret token, compute the HMAC SHA-256 hash of the signature base string.
5. Compare signatures: the computed hash should match the v1 value in the X-Signature header. If they match, the event is verified.

Example in Node.js

const express = require('express');
const bodyParser = require('body-parser');
const crypto = require('crypto');

const app = express();
const PORT = 3000;
const SECRET = 'your_secret_key_here';  // Replace with your secret token

app.use(bodyParser.json());

app.post('/webhook-endpoint', (req, res) => {
    const receivedBody = JSON.stringify(req.body);

    // Extract t and v1 from the X-Signature header
    const signatureHeader = req.get('X-Signature') || '';
    const receivedTimestamp = (signatureHeader.match(/t=(\d+)/) || [])[1];
    const receivedSignature = (signatureHeader.match(/v1=([\w]+)/) || [])[1];

    // Construct the signature base string
    const signatureBaseString = `${receivedTimestamp}.${receivedBody}`;
    // Compute the HMAC SHA-256 signature
    const computedSignature = crypto
        .createHmac('sha256', SECRET)
        .update(signatureBaseString)
        .digest('hex');

    // Compare the signatures
    if (computedSignature === receivedSignature) {
        console.log('Webhook verified!');
        res.status(200).send('Verified');
    } else {
        console.log('Verification failed!');
        res.status(400).send('Verification failed');
    }
});

app.listen(PORT, () => {
    console.log(`Server is running on port ${PORT}`);
});

Webhook payload

Webhooks are sent to your endpoint as HTTP POST requests with a JSON-formatted body. Every payload is made up of:

• The event response — details about the event that fired, under data.
• Generic metadata — sent with every payload, such as type, timestamp, and app_token.
• Additional user & company properties — the user and company objects, containing whichever properties you selected in Data setup.

Send data only to third-party systems you trust — webhook payloads can contain personally identifiable information (PII).

Flows

{
  "type": "flows.seen" || "flows.completed" || "flows.dismissed",
  "timestamp": 1679578625,
  "app_token": "NX-bd46697c",
  "data": {
    "type": "flow",
    "action": "seen" || "completed" || "dismissed",
    "id": 1,
    "hostname": "demo.userpilot.io",
    "pathname": "/dashboard",
    "user": {
      "user_id": "1",
      "name": "John Doe",
      "email": "[e-mail]"
      //... rest of chosen user properties
    },
    "company": {
      "id": "1",
      "name": "Userpilot"
      //... rest of chosen company properties
    }
  }
}

Checklists

{
  "type": "checklist.seen" || "checklist.completed" || "checklist.dismissed",
  "timestamp": 1679578625,
  "app_token": "NX-bd46697c",
  "data": {
    "type": "checklist",
    "action": "seen" || "completed" || "dismissed",
    "id": 1,
    "hostname": "demo.userpilot.io",
    "pathname": "/dashboard",
    "user": {
      "user_id": "1",
      "name": "John Doe",
      "email": "[e-mail]"
      //... rest of chosen user properties
    },
    "company": {
      "id": "1",
      "name": "Userpilot"
      //... rest of chosen company properties
    }
  }
}

Surveys

{
 "timestamp": 1679578625,
 "app_token": "NX-bd46697c",
 "type": "surveys.seen" || "surveys.completed" || "surveys.dismissed",
 "data": {
  "id": 1,
  "action": "seen" || "completed" || "dismissed",
  "title": "UI/UX Survey",
  "type": "survey",
  "hostname": "run.userpilot.io/",
  "pathname": "users/",
  "user": {
      "user_id": "1",
      "name": "John Doe",
      "email": "[e-mail]"
      //... rest of chosen user properties
    },
   "company": {
      "id": "1",
      "name": "Userpilot"
      //... rest of chosen company properties
    }
  "answers": [
     {
      "id": 1,
      "question": "Rate your overall product experience so far",
      "type": "likert_scale",
      "answer": 5,
    },
    {
      "id": 2,
      "question": "Which feature would you like to see the most?"
      "type": "multiple_choice",
      "answer": "Session Replay"
    },
    {
      "id": 3,
      "question": "Anything we could improve?",
      "type": "open_text",
      "answer": "Sort table entries by column"
     }
...
    ]
  }
}

NPS

{
  "type": "nps.feedback",
  "app_token": "NX-bd46697c",
  "timestamp": 1679578619,
  "data": {
    "action": "feedback",
    "survey_question": "How likely it is that you would recommend us to your friends?",
    "score": 10,
    "follow_up_question": "Why did you choose this score? ",
    "feedback": "Great Product",
    "hostname": "demo.userpilot.io",
    "pathname": "/dashboard",
    "user": {
      "user_id": "1",
      "name": "John Doe",
      "email": "[e-mail]"
      //... rest of chosen user properties
    },
    "company": {
      "id": "1",
      "name": "Userpilot"
      //... rest of chosen company properties
    }
  }
}

Feature Tags (Legacy)

{
  "type": "feature_tag.clicked" || "feature_tag.hover" || "feature_tag.text_input",
  "timestamp": 1679578625,
  "app_token": "NX-bd46697c",
  "data": {
    "type": "feature_tag",
    "action": "clicked" || "hover" || "text_input",
    "id": 1,
    "hostname": "demo.userpilot.io",
    "pathname": "/dashboard",
    "user": {
      "user_id": "1",
      "name": "John Doe",
      "email": "[e-mail]"
      //... rest of chosen user properties
    },
    "company": {
      "id": "1",
      "name": "Userpilot"
      //... rest of chosen company properties
    }
  }
}

Forms

{
  "type": "forms.submitted",
  "timestamp": 1679578625,
  "app_token": "NX-bd46697c",
  "data": {
    "type": "forms",
    "action": "submitted",
    "id": 1,
    "hostname": "demo.userpilot.io",
    "pathname": "/dashboard",
    "user": {
      "user_id": "1",
      "name": "John Doe",
      "email": "[e-mail]"
      //... rest of chosen user properties
    },
    "company": {
      "id": "1",
      "name": "Userpilot"
      //... rest of chosen company properties
    }
  }
}

Tracked Events

The example below shows the payload for a tracked event fired through a flow button’s action settings:

{
  "type": "button_tracked_event.occurred",
  "timestamp": 1679578625,
  "app_token": "NX-bd46697c",
  "data": {
    "type": "button_tracked_event",
    "action": "occurred",
    "id": 1,
    "hostname": "demo.userpilot.io",
    "pathname": "/dashboard",
    "user": {
      "user_id": "1",
      "name": "John Doe",
      "email": "[e-mail]"
      //... rest of chosen user properties
    },
    "company": {
      "id": "1",
      "name": "Userpilot"
      //... rest of chosen company properties
    }
  }
}

Events tracked directly through the tracking API follow the same overall envelope — type, timestamp, app_token, and a data object identifying the event, the page it happened on, and the user and company it’s attached to.

Labeled Events, Tagged Pages, Mobile content, and Workflows

These event types follow the same envelope shape as the events above — a top-level type, timestamp, and app_token, and a data object with the event’s type, action, id, and (where applicable) the user and company objects you configured in Data setup. If you need the exact schema for one of these while you build your integration, reach out to [e-mail].

Emails

{
  "id": "9f2c1a04-7b3e-4a51-9c88-2d0f5e6a1b77",
  "type": "emails.unsubscribed" || "emails.resubscribed",
  "timestamp": 1754392802,
  "app_token": "NX-bd46697c",
  "environment": "production",
  "data": {
    "type": "email",
    "action": "unsubscribed" || "resubscribed",
    "id": 3,
    "source": "preference_centre",
    "user": {
      "user_id": "1",
      "email": "[e-mail]"
    }
  }
}

A few things are specific to this event:

• data.id is the subscription type ID, or -1 when the change applies to every email. Someone who unsubscribes from two subscription types produces two events.
• data.source is one of preference_centre, one_click, api, import, or manual, and is what the from source filter in Data setup selects on.
• data.user.user_id can be null. Unsubscribes are tracked by email address, so an imported address that belongs to no Userpilot user still produces an event.
• User and company properties aren’t included, since there may be no user behind the address. email is always present.
• environment reflects whether Send staging data only was on when the event was sent.

Every event carries a top-level id, so key on it if you want to be safe against a duplicate delivery, and read timestamp as the time the change happened. Each delivery and the response it got show up in the webhook’s log.

Limitations

• Webhooks are available on Growth and Enterprise plans only.
• A webhook can include up to 30 user and company properties combined.
• Only events that happen after the webhook is saved and enabled are sent — there’s no way to backfill or replay historical events through a webhook. For historical or bulk data, use Data Sync instead.
• An event only fires if its category is toggled on in Data setup, and only for the specific items and statuses you’ve selected.
• Email events never include user or company properties, since an unsubscribe can be recorded against an email address with no associated Userpilot user.
• Test sends don’t write real data — they won’t unsubscribe a user, mark a flow completed, or otherwise change anything in your account.

---

For any questions or concerns, please reach out to [e-mail]