Webhooks

Overview

Webhooks (AKA callbacks) is a powerful tool to create a custom integration between Userpilot and your own app or third-party systems.

When activated, Userpilot will be sending real-time notifications to the defined end-point whenever certain events happen. These notifications will happen without any delay to allow you to make time-sensitive data-driven decisions.

Common Use Cases

  • Fire workflows in third-party platforms such as Zapier or Workato
  • Sending an email campaign when a user submits a certain NPS score
  • Sending content engagement events to your analytical tools for analysis in real-time
  • Notify your back-end system when an event occurs in Userpilot
  • Send real-time updates to CRM platforms like Hubspot
  • Send real-time notifications to Slack channels after users take an action in Userpilot
  • Trigger an email when a user clicks on a button in one of the flows.


Events 

Webhooks can be created for any of these events:

  •  Flows: Completed, Started, Dismissed
  •  Checklists: Completed, Started, Dismissed

  •  NPS: Score, Dismissed, Feedback
  •  Forms: Submitted
  •  Feature Tags: Click, Hover, Text Input
  •  Button Tracked Events: Tracked through the button action settings in a flow

How to create a Webhook

Navigate to the Integrations page under Configure, then to the Webhooks tab. From here:
  1. Click on Create Webhook to initiate the creation pop-up.
  2. Give your Webhook a descriptive name and specify the endpoint where your events will be sent.
  3. Click Create.
  4. Select the Events that you would like to send in your Webhook from the Events list
  5. You can also include up to 10 user/company properties and a secret token to secure your requests.

Note: We strongly recommend including the secret token to ensure requests are coming from Userpilot and nobody else. The complexity of this secret will vary based on your security protocol requirements.

  6.  Toggle the Event so that the events are sent live

  7. Click on Save and toggle the Status column to enable the Webhook.

Important note: Make sure your event is toggled before saving or the events won't be sent


Testing Webhook Events

You can send a test event before enabling the webhook live. Once you have configured all the settings mentioned in the steps above, you can click on the "Send Test" button. 


Webhook Payload Schema

Webhooks are sent to your specified destination endpoint as  HTTP POST requests with a JSON-formatted body. You can find the payload information with a sample request below.

The Event Response
This part of the payload includes information about the triggered event.

Generic Metadata
This part of the payload includes default information sent with every payload - e.g. user id, app token, etc.

Additional User & Company Properties
This part of the payload includes user and company objects containing properties you've opted to send in your Webhook

Note: We strongly recommend sending data only to third party systems you trust as Webhook information may contain personally identifiable information (PII)
Checklist Seen
{
    "app_token": "abcd1234",
    "data": {
        "action": "seen",
        "id": 11,
        "pathname": null,
        "step": null,
        "type": "checklist",
        "company": {
            "company_id": "company #1",
            "plan": "standard"
        },
        "user": {
            "browser_language": "en",
            "country_code": "US",
            "device_type": "Desktop",
            "hostname": "some.host.com",
            "name": "John Doe",
            "operating_system": "Mac",
            "sessions": 120,
            "user_agent": "Chrome - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
            "user_id": "user_123"
        }
    },
    "id": "req_aBDfQs7qOvAAtacHvlkLSBepn",
    "timestamp": 1665914206,
    "type": "checklist.seen"
}
NPS Feedback
{
    "app_token": "abcd1234",
    "data": {
        "action": "feedback",
        "id": 1,
        "pathname": null,
        "step": null,
        "type": "nps",
        "score": 7,
        "feedback": "Great product!",
        "company": {
            "company_id": "company #1",
            "plan": "standard"
        },
        "user": {
            "browser_language": "en",
            "country_code": "US",
            "device_type": "Desktop",
            "hostname": "some.host.com",
            "name": "John Doe",
            "operating_system": "Mac",
            "sessions": 120,
            "user_agent": "Chrome - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
            "user_id": "user_123"
        }
    },
    "id": "req_aBDfQs7qOvAAtacHvlkLSBepn",
    "timestamp": 1665914206,
    "type": "nps.feedback"
}

Feature Tag Hover
{
    "app_token": "abcd1234",
    "data": {
        "action": "hover",
        "id": 4,
        "type": "feature_tag",
        "company": {
            "company_id": "company #1",
            "plan": "standard"
        },
        "user": {
            "browser_language": "en",
            "country_code": "US",
            "device_type": "Desktop",
            "hostname": "some.host.com",
            "name": "John Doe",
            "operating_system": "Mac",
            "sessions": 120,
            "user_agent": "Chrome - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
            "user_id": "user_123"
        }
    },
    "id": "req_aBDfQs7qOvAAtacHvlkLSBepn",
    "timestamp": 1665914206,
    "type": "feature_tag.hover"
}

If you have any questions you please reach out to us at support@userpilot.co

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.