Test a Webhook

Use the POST /v1/webhooks/{webhook_id}/test endpoint to send a mock event payload to your webhook's URL. This lets you verify that your server receives and processes deliveries correctly without waiting for a real event.

Basic Usage

Send a test delivery to a webhook:

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

This sends a mock notification using the webhook's subscribed event type.

Parameters

Response

The response tells you whether your endpoint received the delivery successfully:

{
  "success": true,
  "delivery": {
    "status_code": 200,
    "response_time_ms": 150,
    "timestamp": "2026-02-27T12:00:00Z"
  },
  "payload": {
    "event_id": "evt_mock_abc123",
    "event_type": "deed.transfer",
    "links": [
      {
        "version": "1",
        "url": "https://api.whitepages.com/v1/events/evt_mock_abc123"
      }
    ]
  }
}

The payload field shows what was sent to your endpoint. This is a lightweight notification containing the event type and a link to retrieve the full event details using the Events API.

What Your Endpoint Receives

Your webhook URL receives a POST request with the following payload:

{
  "event_id": "evt_mock_abc123",
  "event_type": "deed.transfer",
  "links": [
    {
      "version": "1",
      "url": "https://api.whitepages.com/v1/events/evt_mock_abc123"
    }
  ]
}

Each entry in links contains a version string and a url pointing to the full event resource.

Diagnosing Failures

If success is false, check the delivery.status_code to diagnose the issue:

For full request and response schemas, see the Test a webhook delivery API reference.