Webhooks let you receive real-time notifications when enrichment workflows complete, instead of polling the status endpoint.
How webhooks work
Provide a webhook URL when submitting an enrichment request via the API.
When the enrichment completes, Cleanlist sends a POST request to your URL with the results.
Your endpoint should return a 2xx status code within 10 seconds to acknowledge receipt.
Requirements
Your webhook endpoint must be HTTPS and publicly accessible.
It must respond with a 2xx status within 10 seconds.
If delivery fails, Cleanlist retries up to 5 times.
Troubleshooting failed webhooks
Check the delivery log endpoint to diagnose issues:
GET /api/v1/public/webhooks/deliveries?workflow_id=your_workflow_id
The log shows attempt number, status, response code, and error messages for each delivery attempt.
Common failure causes
5xx server errors on your endpoint
4xx authentication or routing rejection
Timeout (response took longer than 10 seconds)
DNS or TLS issues
If all 5 delivery attempts fail, results remain available via the status polling endpoint.