Skip to main content

Overview

Webhooks allow you to receive real-time HTTP notifications when events occur in your BounceWatch account. Instead of polling the API, webhooks push data to your server automatically.
Webhooks are required for receiving enrichment results. Set the X-Webhook-URL header on your API requests or configure a default webhook in the API Panel.

Quick Setup

1

Create Endpoint

Create an HTTPS endpoint on your server to receive webhook events.
2

Configure Webhook

Register your endpoint via the API or dashboard.
3

Verify Signatures (Optional)

Optionally validate incoming webhooks using HMAC-SHA256 signatures for enhanced security.
4

Respond Quickly

Return a 2xx status code within 30 seconds.
🧪 Want to test webhooks quickly? Use webhook.site to get a free test URL instantly - no setup required! See testing guide →

Configuring Webhooks

Via API

One URL, every event. There is no events array to subscribe with — your endpoint receives all enrichment events for the account.

Response

The URL must be https://. Placeholder hosts — example.com, your-domain.com, localhost, 127.0.0.1 — are rejected with 422 invalid_webhook_url.

Where your signing secret lives

Your signing secret is created with your account and is not returned by this endpoint. Find it — and rotate it — in API Panel → Webhooks. It looks like whs_ followed by 64 hex characters.
That page also has a Send test webhook button. It signs exactly like a real delivery, so a verifier that accepts the test will accept production traffic. The only difference is _meta.is_test: true in the payload.

Available Events

enrichment.completed

Triggered when a realtime enrichment job completes successfully.
The webhook payload does not contain enrichment data directly. Use the data_url with your API key to fetch the full results.
Triggered when enrichment fails due to a system error. Credits are automatically refunded.
Credits are reserved upfront but automatically refunded if enrichment fails.
Triggered when the domain exists but no enrichment data could be found. Credits are refunded.
Credits are automatically refunded when no data is found for a domain.
Those three are the complete list. There are no credit-balance webhooks — poll GET /account/credits if you want to alert on a low balance, or watch the credits_remaining field returned with cached responses.

Webhook Security (Optional)

Signature verification is optional but strongly recommended for production environments to ensure webhook authenticity.
All webhook requests include security headers for verification:
Sign the raw body exactly as received. Parsing the JSON and re-serialising it changes key order and escaping, and the signature will not match.

Verifying Signatures (Optional)

Always verify webhook signatures to ensure requests are from BounceWatch.

Handling Events

Example of handling different event types:

Retry Policy

If your endpoint doesn’t respond with a 2xx status code, we’ll retry:
After 5 failed attempts the delivery is marked failed and we stop. Nothing is lost — the enrichment itself completed and the data stays available at GET /api/v1/enrichment/{batch_id}/results. Delivery status per batch is visible on the status endpoint under webhook, and in the dashboard.

Best Practices

Respond Quickly

Return 200 immediately, then process async. Don’t make the webhook wait for your business logic.

Always Verify

Always verify webhook signatures. Never trust incoming data without verification.

Handle Duplicates

A retry re-sends the same X-BounceWatch-Batch-ID. Key your processing on it so a redelivery is a no-op.

HTTPS Only

Webhook URLs must be https://. Plain http is rejected when you configure it, both via the API panel and the X-Webhook-URL header.

Testing Webhooks

The easiest way to test webhooks is using webhook.site:
1

Get Your Test URL

Visit webhook.site - you’ll automatically get a unique URL like:
2

Configure the Webhook

Use this URL when configuring your webhook via the API:
Or skip storing it and send X-Webhook-URL: https://webhook.site/YOUR-UNIQUE-ID on individual requests.
3

View Incoming Webhooks

All webhook requests will appear in real-time on your webhook.site dashboard. You can inspect headers, payload, and response details.
webhook.site is free and requires no setup - perfect for quick testing. For local development, you can also use ngrok to expose your localhost.