Webhooks

Last updated:

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 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

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.
  • Start 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.
  • Archive admin events for auditing and compliance.

Prerequisites

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. For more information, see Roles and permissions.

Webhook types

There are two types of webhook in Pendo:

  • 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.
  • Twilio Segment webhooks. Using the Twilio Segment integration, you can create Segment 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 menu 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 corner of the Integrations page.

2. Add the details of your webhook, including:

    • A descriptive Name, such as where the Wwebhook is going and which data are being sent.
    • The Webhook Type (URL or Segment).
    • The Write Key or URL, depending on the webhook you chose.

3. Follow the instructions for either URL webhooks or Segment webhooks, below.

4. Choose an event category type.

    • Select All event categories to send all event categories in your webhook.
    • Select Individual event categories 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 want to display events for specific guides, you must set up additional filtering within the webhook destination.

mceclip0.png

Create a URL webhook

The platform receiving the Pendo Webhook generates a unique URL that Pendo pushes the notification to. 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.

urlwh.png

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 webhook

A Segment webhook requires a Twilio Segment 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.

SegmentWH.png

Turn a webhook off or on

Webhooks are turned off by default, and must be enabled to send data. 

Use the toggle next to your webhook in Settings > Integrations > Webhooks to turn an existing webhook on or odd.

Enable webhook.png

A webhook with a green toggle is actively sending data. Use the same toggle to stop sending data by sliding the toggle back to the greyed-out status.

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 Edit (pencil) and Delete (trashcan) icons.

Edit or delete a webhook.png

The Edit (pencil) icon opens the webhook settings page where you can make changes to the webhook.

The Delete (trashcan) icon permanently removes the webhook after asking you to confirm this decision. To stop data without losing the webhook configuration, use the toggle to turn off the webhook, as described in Turn a webhook off or on.

Example webhook responses

This section provides example response bodies for the following webhook types:

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"

Troubleshooting

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.

Webhook error handling

Pendo continuously monitors webhook error rates. In the case of repeated failed webhook deliveries, Pendo:

  • Automatically turns off the corresponding webhook. This is to prevent further failed deliveries and to mitigate potential disruptions caused by a webhook experiencing high error rates.
  • Sends an email notification to the owner of the webhook, which is typically the person who created the webhook. If the owner of the webhook is no longer in your Pendo subscription, they don't receive an email.
  • Logs the errors in Settings > Error Log for further analysis and resolution. View this page for specific error codes sent by your system.

If you don't make changes to your receiving resource or webhook definition to fix the problem, you're likely to continue generating a high number of errors and the automation automatically turns the webhook back off.

To prevent this from happening, we display an alert at the top of the Webhooks page in Settings > Integrations whenever we've turned off one or more of your webhooks. This alert prompts you to contact Pendo Support to help you identify and resolve the issue. If you've already identified and resolved the issue, contact Pendo Support to turn your webhooks back on.

Frequently asked questions

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.

 

Was this article helpful?
4 out of 10 found this helpful