Webhooks

📘

PDL Webhooks Overview

PDL offers a webhook functionality to receive timely person data updates at scale.

Currently, webhooks are only available for our subscribing enterprise API and Data License customers. They are available to self-serve customers at this time.

If you would like access, please reach out to us.

What is a webhook

A webhook is a method used by applications to enable real-time notifications of specific events to other applications or services over the web. It functions by sending an HTTP POST request to a URL configured by the user whenever a triggering event occurs. Here's a breakdown of its key aspects for your documentation.

Why use webhooks

When integrating PDL into your data pipeline, you might want your system to automatically signal data updates as they happen with our releases, so that your backend systems can execute actions accordingly.

To enable a webhook, you need to work with your PDL team to register the webhook endpoint. After you register them, PDL can push event data to your application’s webhook endpoint when we update records that match your filter criteria. PDL uses HTTPS to send webhook events to your app as a JSON payload that includes a list of ids.

Who can use webhooks

Webhooks are for enterprise customers only. Please reach out to us if you are interested in utilizing them.

How to setup webhooks (Webhook registration)

In order to register a webhook endpoint you will need to work with your PDL team. There are 3 pieces of information required to enable a webhook:

1. Target URL
2. Headers
3. Filters

Target URL

• This is the endpoint you create where we should send the payloads.
• The Target URL must be a secured endpoint using https.

Headers

• This contains any headers we need to use when firing off the endpoint.
• At a minimum, this should contain a shared key for secure authorization for accepting webhook events.

Filters

• These are the types of updates to filter for and multiple can be selected

📘

Using Multiple Filters

If multiple filters are selected, profiles will be returned if any of the associated fields for either filter have been updated (logical OR)

For example, if mobile_phone_number and personal_emails are enabled on a single webhook, a PDL ID will appear twice if both the mobile phone and personal email change in a single release.

Therefore, in some cases, it might be better to create one webhook per filter to reduce potential duplication

The following filters are supported:

What do webhooks send back (Webhook payloads)

• Whenever a webhook has been triggered (i.e. records have been updated in our dataset based on the registered filters), it will send back a JSON payload containing IDs of the updated records.
  • Payloads are sent in batches of 1,000 ids
  • These are sent once per month, around the time of when our new data is released into the API and post DL delivery

🚧

Webhook Delivery Errors

In the event of a failure (i.e. your server does not return a 200), we will not automatically resend. Instead, please reach out to your PDL Team to resend the current batch. We will need to resend the entire batch when we do resend.

Example Response

[
    "9adnit66-hdZ5lkBbq-AOQ_0000",
    "YraxDoP16jzyjfxtn-1XJQ_0000",
    "6Wu6sKeyNfaLF3CVBgoysg_0000",
    "MRXuwdbvx-poOxpPIPYO9A_0000",
    "9R7GG5mBULdNjHWbQnRsJA_0000",
    ...
]