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.
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
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 likewhs_ followed by 64 hex characters.
Available Events
enrichment.completed
enrichment.completed
Triggered when a realtime enrichment job completes successfully.
enrichment.failed
enrichment.failed
Triggered when enrichment fails due to a system error. Credits are automatically refunded.
Credits are reserved upfront but automatically refunded if enrichment fails.
enrichment.no_data_found
enrichment.no_data_found
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.
Verifying Signatures (Optional)
Always verify webhook signatures to ensure requests are from BounceWatch.- Node.js
- Python
- PHP
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.

