Webhooks
Get a POST when a search finishes.
Pass webhook_url on create search. When that search finishes, the worker POSTs the result to that URL. Get search stays the source of truth. A missed webhook does not change the stored result.
The URL must be http or https and must resolve to a public address. A private or loopback address returns 422 invalid_webhook_url, and no search is created. A deployment can set WEBHOOK_ALLOW_PRIVATE_URLS=1 to allow those addresses for local testing.
Event
The body is JSON. data is the same search result you get from GET, including status and usage.
type | When |
|---|---|
search.completed | The search finished with status completed or partial. |
search.failed | The search finished with status failed. |
{
"event_id": "evt_example",
"type": "search.completed",
"created_at": "2026-10-14T15:00:00Z",
"job_id": "src_example",
"data": { "job_id": "src_example", "status": "completed" }
}event_id stays the same if the delivery is retried. Use it to ignore a duplicate.
Headers:
| Header | Value |
|---|---|
X-Sourcely-Event | The type value. |
X-Sourcely-Delivery | The event_id. |
Reply with any 2xx to acknowledge. A 429 or 5xx, or a connection failure, is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, and 6 hours. Any other 4xx is not retried. Redirects are not followed.
Next-page and claim refetch do not send a webhook.