Webhooks push out real-time notifications to other services when certain events happen.
Webhooks are different from APIs, which require a request to pull information from other services. Most services connected with an API have a 15-minute interval (or more) between requests. Webhooks send information immediately, without a request.
Use cases for Webhooks
Webhooks are useful for situations where real-time notification is critical for your awareness or customer communications. They allow you to drive workflows across your business based on real-time events that occur in Pendo. For example, you might want to:
- Send event information to a provider such as Segment.com to then be routed to other systems.
- Fire workflows in other platforms like AWS Lambdas or Zapier.
- Send real-time updates to CRM platforms with Pendo events, like Zendesk Sunshine.
- Send events to third-party SIEM providers for analysis in real-time.
- Archiving admin events for auditing and compliance.
Use Webhooks to send automated messages or information to other services when something happens in Pendo. Events that can push a notification with Webhooks include:
- Guide Displayed
- Web Track Event Received
- NPS Surveys (Displayed / Submitted)
- Polls (Displayed / Submitted)
- When a Visitor is first seen in-app
- When an Account is first seen in-app
Requirements
To use Poll and NPS Events with Webhooks, you must have Pendo Agent Version 2.33.0 or higher.
You must also have Pendo Admin permissions to configure and manage Webhooks.
Webhook Types
There are two types of Webhooks:
- URL Webhooks. The platform you're sending a Webhook notification to generates a unique URL for each Webhook. Most platforms that accept webhooks use a URL.
- Segment.com Webhooks. Using Segment.com integration, you can create Segment.com Webhooks to send events in Segment's preferred format.
Webhooks typically send event information through a URL.
View existing Webhooks
To see a list of active and inactive Webhooks in Pendo, navigate to Settings > Integrations in the left-side navigation and select the Webhooks tab.
Create a Webhook
To create a Webhook, navigate to Settings > Integrations in the left-side navigation and select the Webhooks tab. From here:
1. Select the + Add Webhook button in the top-right of the Integrations page.
2. Add the details of your Webhook, including:
-
- A descriptive Name, such as where the Webhook is going and which data are being sent.
- The Webhook Type (URL or Segment.com).
- The Write Key or URL, depending on the Webhook you chose.
3. Follow the instructions for either URL Webhooks or Segment.com Webhooks, below.
4. Choose an event category type.
-
- Selecting All event categories sends all event categories in your Webhook.
- Selecting Individual event categories allows you to choose which event categories you want to send in your Webhook.
There's no additional filtering in Pendo after you choose event categories. As an example, if you choose the event category "Guides", Pendo sends a notification for every Guide display event. If you're interested displaying events for specific guides, you must set up additional filtering within the webhook destination.
Create a URL Webhook
The platform receiving the Pendo Webhook generates a unique URL that Pendo pushes the notification too. When you have the webhook URL, continue with the webhook setup in Pendo.
1. Add the destination URL. When an event is triggered, information is be sent to this URL.
2. Select Test to send a sample payload and validate that your destination accepts the event payload.
3. Enter a value into the Secret field to validate that information received by the URL is from the correct trusted source. Your secret can be as simple or complex as your security protocol requires, and can include special characters.
In the webhook POST "X-Pendo-Signature", the value is set to sha256 HMAC of the serialized message using the secret as the key. This is expected to change in each post because the body of the webhook is used in this field. The body changes with each event sent. We followed the experience of Github's webhook process, described in their Securing your webhooks article.
Warning: Webhook event information can contain personally identifiable information (PII) depending on your installation and data mappings. Use a destination or service that you trust before testing or enabling your Webhook.
Create a Segment.com Webhook
A segment.com Webhook requires a Segment.com account.
1. In Segment, set up Pendo as a Source to retrieve a Write Key. For more information, see Segment's Pendo Source article.
2. In Segment, navigate to Overview > Installation and copy the write key. For more information, see Segment's Locate your Write Key article.
3. Copy the key into the Pendo Webhook you're creating, under Write Key.
Enable or disable a Webhook
Webhooks are disabled by default, and must be enabled to send data.
Use the toggle next to your Webhook in Settings > Integrations > Webhooks to enable or disable an existing Webhook.
A Webhook with a green slider is actively sending data. Use the same toggle to stop sending data by sliding the toggle back to the greyed out slider.
Edit or delete a Webhook
To edit or remove an existing Webhook in Pendo, navigate to Settings > Integrations in the left-side navigation and select the Webhooks tab. From here, hover over an existing Webhook to display the pencil (edit) and trashcan (delete) icons.
The pencil (edit) icon opens the Webhook settings page where you can make changes to the Webhook.
The trashcan (delete) icon permanently removes the Webhook after asking you to confirm this decision. To stop data without losing the Webhook configuration, use the toggle deactivate the Webhook, as described under Enable or disable a Webhook.
Example webhook responses
This section provides example response bodies for the following webhook types:
- Guide displayed
- Poll displayed
- Poll submitted
- NPS displayed
- NPS submitted
- Visitor created
- Account created
- Track Event received
Guide displayed
{
"app": {
"id": -323232,
"name": "test_application",
"platform": "web"
},
"accountId": "Webhook Account",
"subscription": {
"id": 4802463602049999,
"name": "test_application"
},
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
"event": "guideDisplayed",
"properties": {
"guideId": "Kg92trd4yOzpDb2inI5eTOdcR0U",
"guideProperties": {
"createdAt": 1615411012615,
"createdByUser": {
"username": "pendo-user@example.com"
},
"id": "Kg92trd4yOzpDb2inI5eTOdcR0U",
"lastUpdatedAt": 1618322253073,
"lastUpdatedByUser": {
"username": "pendo-user@example.com"
},
"name": "Poll 1 - Test",
"steps": [
{
"id": "UgG7AtWEXNuvHBBcTqSQ8NxGvAU",
"lastUpdatedAt": 1618322251476,
"resetAt": 1617633741117,
"type": "building-block"
}
]
},
"guideStepId": "UgG7AtWEXNuvHBBcTqSQ8NxGvAU",
"language": "en-US"
},
"timestamp": 1626803876,
"visitorId": "Webhook Visitor",
"uniqueId": "f9610795860d89fe29491846fe297bcc922e460b"
Poll displayed
{
"app": {
"id": -323232,
"name": "test_application",
"platform": "web"
},
"accountId": "Webhook Account",
"subscription": {
"id": 4802463602049999,
"name": "test_application"
},
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
"event": "pollDisplayed",
"properties": {
"guideId": "Kg92trd4yOzpDb2inI5eTOdcR0U",
"guideProperties": {
"createdAt": 1615411012615,
"createdByUser": {
"username": "pendo-user@example.com"
},
"id": "Kg92trd4yOzpDb2inI5eTOdcR0U",
"lastUpdatedAt": 1618322253073,
"lastUpdatedByUser": {
"username": "pendo-user@example.com"
},
"name": "Poll 1 - Test",
"steps": [
{
"id": "UgG7AtWEXNuvHBBcTqSQ8NxGvAU",
"lastUpdatedAt": 1618322251476,
"resetAt": 1617633741117,
"type": "building-block"
}
]
},
"guideStepId": "UgG7AtWEXNuvHBBcTqSQ8NxGvAU",
"language": "en-US"
},
"timestamp": 1626803876,
"visitorId": "Webhook Visitor",
"uniqueId": "3373ffb08b355be4e53e3816a84a7bcdd4fbc6ed"
}
Poll submitted
{
"app": {
"id": -323232,
"name": "test_application",
"platform": "web"
},
"accountId": "Webhook Account",
"subscription": {
"id": 4802463602049999,
"name": "test_application"
},
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
"event": "pollSubmitted",
"properties": {
"guideId": "Kg92trd4yOzpDb2inI5eTOdcR0U",
"guideProperties": {
"createdAt": 1615411012615,
"createdByUser": {
"username": "pendo-user@example.com"
},
"id": "Kg92trd4yOzpDb2inI5eTOdcR0U",
"lastUpdatedAt": 1618322253073,
"lastUpdatedByUser": {
"username": "pendo-user@example.com"
},
"name": "Poll 1 - Test",
"steps": [
{
"id": "UgG7AtWEXNuvHBBcTqSQ8NxGvAU",
"lastUpdatedAt": 1618322251476,
"resetAt": 1617633741117,
"type": "building-block"
}
]
},
"guideStepId": "UgG7AtWEXNuvHBBcTqSQ8NxGvAU",
"language": "en-US",
"pollResponses": [
{
"duration": 11964,
"pollId": "afxd8uayh4u",
"pollType": "PositiveNegative",
"response": 1
},
{
"duration": 11964,
"pollId": "rtzh4txwz4f",
"pollType": "NumberScale",
"response": 2
},
{
"duration": 11964,
"pollId": "pspats0sy5f",
"pollType": "FreeForm",
"response": "Open Text Answer"
},
{
"duration": 11964,
"pollId": "braocb22n4j",
"pollType": "PickList",
"response": "Product Manager"
}
]
},
"timestamp": 1626803991,
"visitorId": "Webhook Visitor",
"uniqueId": "fbd70226173184006adc31b810b93f36bb52ec02"
}
NPS displayed
{
"app": {
"id": -323232,
"name": "test_application",
"platform": "web"
},
"accountId": "Webhook Account",
"subscription": {
"id": 4802463602049999,
"name": "test_application"
},
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
"event": "npsDisplayed",
"properties": {
"guideId": "FjHsQ7S8z0ircYxe3vO4GHawvwI",
"guideProperties": {
"createdAt": 1591024335185,
"createdByUser": {
"username": "pendo-user@example.com"
},
"id": "FjHsQ7S8z0ircYxe3vO4GHawvwI",
"lastUpdatedAt": 1626804377122,
"lastUpdatedByUser": {
"username": "pendo-user@example.com"
},
"name": "Quarterly NPS",
"steps": [
{
"id": "WkaB4F2droQ5sSqd-FvC7H9coJQ",
"lastUpdatedAt": 1619546765626,
"resetAt": 1592592811776,
"type": ""
},
{
"id": "oFs_eA1lF61Ywsg0js945UcG798",
"lastUpdatedAt": 1605640318713,
"resetAt": 1592592811776,
"type": ""
}
]
},
"guideStepId": "WkaB4F2droQ5sSqd-FvC7H9coJQ",
"language": "en-US"
},
"timestamp": 1626804384,
"visitorId": "Webhook Visitor",
"uniqueId": "b1f15067d47df50a1207dc2d0ce6171a40f8304e"
}
NPS submitted
{
"app": {
"id": -323232,
"name": "test_application",
"platform": "web"
},
"accountId": "Webhook Account",
"subscription": {
"id": 4802463602049999,
"name": "test_application"
},
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
"event": "npsSubmitted",
"properties": {
"guideId": "FjHsQ7S8z0ircYxe3vO4GHawvwI",
"guideProperties": {
"createdAt": 1591024335185,
"createdByUser": {
"username": "pendo-user@example.com"
},
"id": "FjHsQ7S8z0ircYxe3vO4GHawvwI",
"lastUpdatedAt": 1626804377122,
"lastUpdatedByUser": {
"username": "pendo-user@example.com"
},
"name": "Quarterly NPS",
"steps": [
{
"id": "WkaB4F2droQ5sSqd-FvC7H9coJQ",
"lastUpdatedAt": 1619546765626,
"resetAt": 1592592811776,
"type": ""
},
{
"id": "oFs_eA1lF61Ywsg0js945UcG798",
"lastUpdatedAt": 1605640318713,
"resetAt": 1592592811776,
"type": ""
}
]
},
"guideStepId": "WkaB4F2droQ5sSqd-FvC7H9coJQ",
"language": "en-US",
"nps": {
"rating": 9,
"reason": "Keep up the great work!",
"source": "web"
}
},
"timestamp": 1626804431,
"visitorId": "Webhook Visitor",
"uniqueId": "ccb0f95474ae8b630ede92f8f8dbac03cddfc1c3"
}
Visitor created
{
"app": {
"id": -323232,
"name": "test_application",
"platform": "web"
},
"accountId": "Webhook Account",
"subscription": {
"id": 4802463602049024,
"name": "test_application"
},
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
"event": "visitorCreated",
"properties": {
"browserName": "Chrome",
"browserVersion": "91.0.4472",
"sampleGroup": 17
},
"timestamp": 1626803875,
"visitorId": "Webhook Visitor",
"uniqueId": "1a2c20ed531bf920781d7f1449968b772840e36c"
Account created
{
"app": {
"id": -323232,
"name": "test_application",
"platform": "web"
},
"accountId": "Webhook Account",
"subscription": {
"id": 4802463602049999,
"name": "test_application"
},
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
"event": "accountCreated",
"properties": {},
"timestamp": 1626803875,
"visitorId": "Webhook Visitor",
"uniqueId": "38993a6dd7ff256c0112528ca44b291255603647"
}
Track Event received
{
"app": {
"id": -323232,
"name": "test_application",
"platform": "web"
},
"accountId": "Webhook Account",
"subscription": {
"id": 4802463602049999,
"name": "test_application"
},
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
"event": "trackEventReceived",
"properties": {
"eventProperties": {
"fromTier": "basic",
"toTier": "pro"
},
"name": "Account Upgraded",
"source": "web"
},
"timestamp": 1626804144,
"visitorId": "Webhook Visitor",
"uniqueId": "75c32838012a8311fba2b902857c2e848d98f457"
Frequently Asked Questions
Why am I receiving a timeout error?
Webhooks typically time out if they exceed the 5 minute limit. Queries that take longer than 5 minutes time out and result in a 408 error.
If I receive an error, will Pendo try to send the event again?
If Pendo receives a 429 error or an error message from 500 to 599 range, Pendo will retry up to 5 times.
Will I receive events if a visitor or account is created first via API bulk metadata endpoint?
No, Creating the visitor or account via API does not trigger the Webhook until the visitor is identified in-app.
Will I receive events from Excluded visitors?
No, Pendo will not send an event to your destination if a visitor is excluded.
Can I use Slack as a Webhook destination?
No, when using Slack as a Webhook destination it is looking for the POST to be in a specific format. You'll need to use a tool such as Zapier to translate the JSON body that Pendo is sending into a format that Slack expects.