1. Pendo Help Center
  2. Integrations
  3. Integration technology

Webhooks

Last updated:

Webhooks send real-time notifications to other services when specific events occur.

Webhooks differ from APIs, which require a request to retrieve information from other services. Most services connected to 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 an event occurs in Pendo. Events that can push a notification with webhooks include:

  • Page loaded.
  • Feature clicked.
  • Guide displayed.
  • Track Event received.
  • NPS surveys (displayed and submitted).
  • Polls (displayed and submitted).
  • When a visitor is first seen in-app.
  • When an account is first seen in-app.
  • When a visitor unsubscribes from emails sent through Orchestrate.
  • Frustration signals (Intercom webhooks only).

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 Twilio Segment, 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 real-time analysis.
  • Archive admin events for auditing and compliance.
  • Send unsubscribe events from Orchestrate to third party messaging tools, so you can maintain a consistent database of users who’ve unsubscribed from your emails.

Prerequisites

  • To use Poll and NPS Events with webhooks, you must have Pendo Web SDK Version 2.33.0 or above.
  • You must also have subscription admin permissions to configure and manage webhooks. For more information, see Roles and permissions.
  • To create an Intercom webhook, you also need an Intercom workspace and an Intercom access token.

Webhook types

There are three types of webhooks 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.
  • Intercom webhooks. Send frustration signals to Intercom in Intercom's preferred format. You can use these events to trigger Intercom Workflows, Fin conversations, or other automations when visitors show signs of friction in your app.

Webhooks typically send event information through a URL. 

View existing webhooks

To see a list of active and inactive webhooks in Pendo, go to Settings > Integrations from the top-right corner, then select the Webhooks tab.

Create a webhook

To create a webhook, select Settings > Integrations in the top-right corner of Pendo, then 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 webhook is going and which data is being sent.
    • The webhook Type (URL, Segment, or Intercom).
    • The Write Key, URL, or Access Token, depending on the webhook you chose.
  3. Follow the instructions for URL webhooks, Segment webhooks, or Intercom webhooks below.
  4. Select the event categories you want to send in your webhook.
    • Check the box next to an event category to include it.
    • For categories like Pages, Features, Track Events, Guides, NPS Surveys, and Polls, you can select specific items to trigger the webhook.
    • For categories Accounts created, Visitors created, and Emails, you receive notifications for all of these events.

Note: Intercom webhooks send only frustration signals, configured directly in the Intercom webhook settings.

If you select a category without specifying any items, Pendo sends a notification for every event in that category by default. Selecting specific items allows you to filter the webhook payloads directly in Pendo.

webhooks-subscription-events.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

Create an Intercom webhook

An Intercom webhook sends frustration signals from Pendo to Intercom in Intercom's preferred format. You can use these events to trigger Intercom Workflows, Fin conversations, or other automations when visitors show signs of friction in your app. For more information on the setup, see Connect behavioral data to the Fin AI Agent (beta).

An Intercom webhook requires an Intercom workspace and an Intercom access token.

To set up an Intercom webhook:

  1. For Region, select the region that matches your Intercom workspace.
  2. Paste your Intercom access token into Access Token. This is available in the Intercom Developer Hub.
  3. Under Frustration Signals, select the frustration types you want to send to Intercom:
    • Rage Click. A visitor repeatedly clicks in a focused area of your UI.
    • Error Click. A visitor clicks an element that triggers a client-side JavaScript error.
    • U-Turn. A visitor navigates to a Page and returns to the previous Page within seven seconds.
add-intercom-webhook.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, go to Settings > Integrations from the top-right corner, then 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:

For Page loaded, Feature clicked, and Track Event received webhooks, the ids field contains only the IDs that match the webhook's configured event selection. If no IDs match, the field is omitted from the payload. Page loaded and Feature clicked payloads include eventProperties and ids but don't include name or source. Track Event received payloads include all four fields.

Page loaded

{
  "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": "pageLoaded",
  "properties": {
    "eventProperties": {},
    "ids": ["pageId1", "pageId2"]
  },
  "timestamp": 1626803875,
  "visitorId": "Webhook Visitor",
  "uniqueId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
}

Feature clicked

{
  "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": "featureClicked",
  "properties": {
    "eventProperties": {
      "elementType": "button"
    },
    "ids": ["feature-xyz789"]
  },
  "timestamp": 1626804250,
  "visitorId": "Webhook Visitor",
  "uniqueId": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1"
}

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",
    "ids": ["trackTypeId-abc123", "trackTypeId-def456"]
  },
  "timestamp": 1626804144,
  "visitorId": "Webhook Visitor",
  "uniqueId": "75c32838012a8311fba2b902857c2e848d98f457"
}

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"

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

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

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

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"

Visitor unsubscribed

{
  "app": {
    "id": -323232,
    "name": "test_application",
    "platform": "web"
  },
  "accountId": "Webhook Account",
  "subscription": {
    "id": 4802463602009999,
    "name": "test_application"
  },
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/11.0.4472.164 Safari/537.36",
  "visitorId": "abc123",
  "eventType": "unsubscribe",
  "timestamp": "2025-10-28T14:05:00Z"
}

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 > Integrations > Webhooks, where you can see which webhook is failing. A link to Review logs appears next to the webhook. You can view the logs, copy them into a text editor, or download them as a JSON file
  • Logs the errors in Settings > Error Log that's failing for further analysis and resolution. View this page for specific error codes sent by your system.

A webhook that's been turned off by Pendo can be turned back on in two ways:

  • If an error with the webhook has occurred within the last 14 days, you can turn the webhook on after reviewing the error logs in Settings > Integrations > Webhooks and confirming that you've identified and resolved the issue.
  • If no error logs are available for a webhook, you can contact Pendo Support to help you to identify and resolve the issue. If you've already identified the issue, contact Pendo Support to turn your webhook 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 in the 500 to 599 range, it will retry up to five 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 doesn't trigger the webhook until the visitor is identified in-app.

Will I receive events from excluded visitors?

No, Pendo won't 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's 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 11 found this helpful

Articles in this section