POST/v1/delivery?squid={squid_hash}

Configure Webhook Delivery

Set up real-time webhook notifications for squid run events

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

run.running

Description:

Run is actively executing

Trigger Condition:

Emitted when a Squid run begins or resumes

run.paused

Description:

Run paused

Trigger Condition:

Emitted when the run is temporarily halted (e.g., account limits reached)

run.done

Description:

Run completed successfully

Trigger Condition:

Emitted when the run finishes without errors

run.error

Description:

Unexpected error occurred

Trigger Condition:

When a run has crashed with an error

Webhook Payload

Lobstr sends a JSON payload to your webhook URL:

json

{
  "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

Type:

string

Description:

Unique identifier for the run (hash)

object

Type:

string

Description:

Always "run"

event

Type:

string

Description:

One of the subscribed Event Types

squid.id

Type:

string

Description:

Squid hash

squid.name

Type:

string

Description:

Human-friendly Squid name

timestamp

Type:

string

Description:

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

Key	Value	Required
Authorization	Token YOUR_API_KEY	Yes
Content-Type	application/json	Yes

Request Body

webhook_fields.urlstring

Required

Your webhook endpoint URL that will receive POST requests

Example: https://your-webhook.com/endpoint

webhook_fields.is_activeboolean

Required

Master switch to enable/disable webhooks

Example: true

webhook_fields.retryboolean

Required

Enable automatic retries for failed webhook deliveries (up to 3 attempts with 15-minute delays)

Example: false

webhook_fields.events.run.runningboolean

Required

Subscribe to run start/resume events

Example: true

webhook_fields.events.run.pausedboolean

Required

Subscribe to run pause events

Example: false

webhook_fields.events.run.doneboolean

Required

Subscribe to run completion events

Example: false

webhook_fields.events.run.errorboolean

Required

Subscribe to run error events

Example: true

Response Field Explanations

webhook_fields.url

string

Configured webhook endpoint URL

Example: https://your-webhook.com/endpoint

webhook_fields.is_active

boolean

Whether webhooks are active

Example: true

webhook_fields.retry

boolean

Whether retry mechanism is enabled

Example: false

webhook_fields.events.run.running

boolean

Subscription status for run.running events

Example: true

webhook_fields.events.run.paused

boolean

Subscription status for run.paused events

Example: false

webhook_fields.events.run.done

boolean

Subscription status for run.done events

Example: false

webhook_fields.events.run.error

boolean

Subscription status for run.error events

Example: true

Parameters

squidstring

Required

The unique identifier (hash) of the squid for which to configure webhook delivery

Example: c106a44a98044ef18acc59986ae10967

Pro Tip

Subscribe only to events you need. For most use cases, run.done and run.error are sufficient.

Warning

Your webhook endpoint must respond within 30 seconds or the delivery will be marked as failed.

Pro Tip

Enable retry for production webhooks to handle temporary network issues or server downtime automatically.

Note

Webhook payloads are sent as JSON with Content-Type: application/json header. Parse the request body to extract event data.

Pro Tip

Use the Test Webhook endpoint to verify your endpoint is accessible and responding correctly before activating webhooks.

Warning

Implement proper authentication/validation in your webhook endpoint to ensure requests are coming from lobstr.io.