Webhook Quickstart | Whitepages API

Walk through the full webhook lifecycle — create, test, and retrieve an event — with real API calls

This interactive walkthrough guides you through the complete webhook lifecycle using your API key. You will create a webhook subscription, send a test delivery, and retrieve the resulting event — all from this page.

Invite-Only Access

Webhooks are currently available by invite only. To request access, contact our support team at api@whitepages.com or visit the Support and Incident Response page.

Supported Regions

Webhooks are currently available for Texas counties only. This walkthrough uses Dallas County, TX as the default region. Browse the full list of supported regions on the Regions page.

Configuration

Enter your API key and the HTTPS endpoint where you want to receive webhook deliveries. Both are only used for requests made from this page.

API Key

Webhook URL

Create Webhook

A webhook subscription tells the API to send notifications to your HTTPS endpoint whenever matching events occur in a region. This request creates a subscription for all deed events (deed.*) in Dallas County, TX.

Request body:

url — Your HTTPS endpoint that receives webhook deliveries. The API sends POST requests to this URL when events occur.
event_type — The event pattern to subscribe to. deed.* matches all deed events (transfers, recordings, etc.).
region — The geographic area to monitor, in type:value format.
name — An optional label to identify this subscription when you have multiple webhooks.

The response includes the created webhook with its id, which you will use in the next step to send a test delivery.

curl -X POST 'https://api.whitepages.com/v1/webhooks/' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://your-endpoint.com/webhooks",
    "event_type": "deed.*",
    "region": "county:tx.dallas",
    "name": "Quickstart Webhook"
  }'

Test Webhook

A test delivery sends a mock event notification to your webhook endpoint. This verifies your server can receive and process webhook payloads without waiting for a real deed event to occur.

What happens during a test:

The API sends a POST request to your webhook URL with a mock event payload containing an event_id, event_type, and a links array.
Your endpoint should respond with a 2xx status code to acknowledge receipt.
The response from this API call tells you whether delivery succeeded, including the status code and response time from your server.

The payload.event_id from the response is used in the next step to retrieve the full mock event.

curl -X POST 'https://api.whitepages.com/v1/webhooks/WEBHOOK_ID/test' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{}'

Retrieve Event

When your endpoint receives a webhook notification, it includes a link to fetch the full event details. This final step retrieves that event using the Events API, completing the lifecycle.

The event payload includes:

jurisdiction — The county and state where the deed was recorded, along with the FIPS code.
property — Address, parcel ID, geolocation, square footage, and other property attributes.
parties — Grantors and grantees involved in the deed transaction, with names, roles, and addresses.
detail — Document type, recorded date, consideration amount, and transaction reason.

This is the same data structure you would receive for real deed events. The mock event uses synthetic data, but the shape is identical to production events.

curl 'https://api.whitepages.com/v1/events/EVENT_ID' \
  --header 'X-Api-Key: YOUR_API_KEY'

Next Steps

Create a Webhook — Full guide with all parameters and options
Event Payload — Detailed breakdown of event data fields
Event Types — All supported event types and their meanings
Regions — Browse and search available webhook regions