Webhooks
Receive lifecycle notifications without polling jobs and runs.
Gluecrawl can send a JSON POST request to your HTTPS endpoint when a subscribed job or run changes state. Each account can configure one endpoint and choose which lifecycle events it receives.
Configure an endpoint
Create an endpoint with POST /v1/webhooks, then subscribe to one or more of these events:
| Event | Sent when |
|---|---|
job.ready | A job has finished mapping and can be run. |
job.failed | A job fails, including an initial queueing failure. |
run.completed | A run has completed, including scheduled runs. |
run.failed | A run fails, including a queueing failure. |
webhook.test is sent only by the test endpoint. It cannot be selected as a subscription.
Your URL must use HTTPS, resolve only to public IP addresses, and must not contain credentials. Gluecrawl validates it when you configure it and immediately before delivery.
Payload
Every delivery has the same envelope. data contains a minimal snapshot from the lifecycle transition; fields that do not apply are null.
{
"id": "evt_01jz4jn9n5ecwk3e3hvqkwv15e",
"type": "run.completed",
"api_version": "2026-07-30",
"created_at": "2026-08-02T14:30:00Z",
"data": {
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"job_status": "ready",
"run_id": "660e8400-e29b-41d4-a716-446655440001",
"run_status": "completed",
"error": null
}
}Treat id as the delivery identifier and api_version as the version of this envelope. Store the identifier if your receiver needs to deduplicate a request.
Delivery behavior
Gluecrawl makes exactly one delivery attempt for each event. A 2xx response marks the delivery as delivered; any other HTTP status, timeout, connection error, or rejected target marks it as failed. Redirects are not followed, and the request times out after 10 seconds.
There are no automatic retries. Use delivery history to inspect the result, and make your receiver return a 2xx response quickly before starting long-running work.
Callback requests send JSON and include User-Agent: Gluecrawl-Webhooks/1.0. Gluecrawl does not currently send a webhook signature, so do not treat that header as authentication.
Disabling an endpoint prevents new lifecycle events from being queued. Deleting one cancels unattempted events and retains its redacted delivery history; the destination URL is removed from that history.