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)

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": "john@userpilot.co"
      //... rest of chosen user properties
    },
    "company": {
      "id": "1",
      "name": "Userpilot"
      //... rest of chosen company properties
    }
  }
}


Checklist
{
  "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": "john@userpilot.co"
      //... rest of chosen user properties
    },
    "company": {
      "id": "1",
      "name": "Userpilot"
      //... rest of chosen company properties
    }
  }
}
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": "john@userpilot.co"
      //... rest of chosen user properties
    },
    "company": {
      "id": "1",
      "name": "Userpilot"
      //... rest of chosen company properties
    }
  }
}

NPS ASK LATER
---------

{
  "type": "nps.ask_later",
  "app_token": "NX-bd46697c",
  "timestamp": 1679578619,
  "data": {
    "action": "ask_later",
    "hostname": "demo.userpilot.io",
    "pathname": "/dashboard",
    "user": {
      "user_id": "1",
      "name": "John Doe",
      "email": "john@userpilot.co"
      //... rest of chosen user properties
    },
    "company": {
      "id": "1",
      "name": "Userpilot"
      //... rest of chosen company properties
    }
  }
}


Feature Tag 
{
  "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": "john@userpilot.co"
      //... rest of chosen user properties
    },
    "company": {
      "id": "1",
      "name": "Userpilot"
      //... rest of chosen company properties
    }
  }
}
Forms submission
{
  "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": "john@userpilot.co"
      //... rest of chosen user properties
    },
    "company": {
      "id": "1",
      "name": "Userpilot"
      //... rest of chosen company properties
    }
  }
}


Button Tracked Event
{
  "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": "john@userpilot.co"
      //... rest of chosen user properties
    },
    "company": {
      "id": "1",
      "name": "Userpilot"
      //... rest of chosen company properties
    }
  }
}

If you have any questions  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.