Configure Webhook Delivery
Set up real-time webhook notifications for squid run events
https://api.lobstr.io/v1/delivery?squid={squid_hash}Configure webhooks to receive real-time HTTP POST notifications when your squid's events occur. Subscribe to specific events like run start, completion, pause, or errors.
Event Types
| Event | Description | Trigger Condition |
|---|---|---|
| run.running | Run is actively executing | Emitted when a Squid run begins or resumes |
| run.paused | Run paused | Emitted when the run is temporarily halted (e.g., account limits reached) |
| run.done | Run completed successfully | Emitted when the run finishes without errors |
| run.error | Unexpected error occurred | When a run has crashed with an error |
Webhook Payload
Lobstr sends a JSON payload to your webhook URL:
{ "id": "c39b1922a5424c3c84a7cb2ec731bc5f", "object": "run", "event": "run.done", "squid": { "id": "8177beb16fdf4e0e8d4b2ba767d1ffb5", "name": "Google Maps Search Export (1)" }, "timestamp": "2025/06/18 17:32:31" }
Payload Fields
| Field | Type | Description |
|---|---|---|
| id | string | Unique identifier for the run (hash) |
| object | string | Always "run" |
| event | string | One of the subscribed Event Types |
| squid.id | string | Squid hash |
| squid.name | string | Human-friendly Squid name |
| timestamp | string | Event timestamp in YYYY/MM/DD HH:MM:SS format (UTC) |
Retry Mechanism
When retry is enabled:
- Failed webhook deliveries are retried up to 3 times
- Retries occur with a 15-minute delay between attempts
Webhook Response Requirements
- Your endpoint should respond within 30 seconds
- Return HTTP 200, 201, or 202 to indicate successful receipt
Headers
AuthorizationstringheaderrequiredYour API authentication token. Value: Token YOUR_API_KEY
Content-TypestringheaderrequiredMust be application/json. Value: application/json
Query Parameters
squidstringqueryrequiredThe unique identifier (hash) of the squid for which to configure webhook delivery. Example: c106a44a98044ef18acc59986ae10967
Request Body
webhook_fields.urlstringrequiredYour webhook endpoint URL that will receive POST requests. Example: "https://your-webhook.com/endpoint"
webhook_fields.is_activebooleanrequiredMaster switch to enable/disable webhooks. Example: true
webhook_fields.retrybooleanrequiredEnable automatic retries for failed webhook deliveries (up to 3 attempts with 15-minute delays). Example: false
webhook_fields.events.run.runningbooleanrequiredSubscribe to run start/resume events. Example: true
webhook_fields.events.run.pausedbooleanrequiredSubscribe to run pause events. Example: false
webhook_fields.events.run.donebooleanrequiredSubscribe to run completion events. Example: false
webhook_fields.events.run.errorbooleanrequiredSubscribe to run error events. Example: true
Response Field Explanations
webhook_fields.urlstringConfigured webhook endpoint URL. Example: "https://your-webhook.com/endpoint"
webhook_fields.is_activebooleanWhether webhooks are active. Example: true
webhook_fields.retrybooleanWhether retry mechanism is enabled. Example: false
webhook_fields.events.run.runningbooleanSubscription status for run.running events. Example: true
webhook_fields.events.run.pausedbooleanSubscription status for run.paused events. Example: false
webhook_fields.events.run.donebooleanSubscription status for run.done events. Example: false
webhook_fields.events.run.errorbooleanSubscription status for run.error events. Example: true
Subscribe only to events you need. For most use cases, run.done and run.error are sufficient.
Your webhook endpoint must respond within 30 seconds or the delivery will be marked as failed.
Enable retry for production webhooks to handle temporary network issues or server downtime automatically.
Webhook payloads are sent as JSON with Content-Type: application/json header. Parse the request body to extract event data.
Use the Test Webhook endpoint to verify your endpoint is accessible and responding correctly before activating webhooks.
Implement proper authentication/validation in your webhook endpoint to ensure requests are coming from lobstr.io.
Code Examples
curl -X POST "https://api.lobstr.io/v1/delivery?squid=YOUR_SQUID_HASH" \ -H "Authorization: Token YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "webhook_fields": { "url": "https://your-webhook.com/endpoint", "is_active": true, "retry": false, "events": { "run.running": true, "run.paused": false, "run.done": false, "run.error": true } } }'
Response
{ "webhook_fields": { "url": "https://your-webhook.com/endpoint", "is_active": true, "retry": false, "events": { "run.running": true, "run.paused": false, "run.done": false, "run.error": true } } }