Skip to main content
POST
/
v1
/
delivery
Configure Webhook Delivery
curl --request POST \
  --url https://api.lobstr.io/v1/delivery \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "webhook_fields.url": "<string>",
  "webhook_fields.is_active": true,
  "webhook_fields.retry": true,
  "webhook_fields.events.run.running": true,
  "webhook_fields.events.run.paused": true,
  "webhook_fields.events.run.done": true,
  "webhook_fields.events.run.error": true
}
'
{
  "webhook_fields.url": "<string>",
  "webhook_fields.is_active": true,
  "webhook_fields.retry": true,
  "webhook_fields.events.run.running": true,
  "webhook_fields.events.run.paused": true,
  "webhook_fields.events.run.done": true,
  "webhook_fields.events.run.error": true
}
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

EventDescriptionTrigger Condition
run.runningRun is actively executingEmitted when a Squid run begins or resumes
run.pausedRun pausedEmitted when the run is temporarily halted (e.g., account limits reached)
run.doneRun completed successfullyEmitted when the run finishes without errors
run.errorUnexpected error occurredWhen 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

FieldTypeDescription
idstringUnique identifier for the run (hash)
objectstringAlways “run”
eventstringOne of the subscribed Event Types
squid.idstringSquid hash
squid.namestringHuman-friendly Squid name
timestampstringEvent 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

​
Authorization
string
required
Your API authentication token. Value: Token YOUR_API_KEY
​
Content-Type
string
required
Must be application/json. Value: application/json

​
Query Parameters

​
squid
string
required
The unique identifier (hash) of the squid for which to configure webhook delivery. Example: c106a44a98044ef18acc59986ae10967

​
Request Body

​
webhook_fields.url
string
required
Your webhook endpoint URL that will receive POST requests. Example: "https://your-webhook.com/endpoint"
​
webhook_fields.is_active
boolean
required
Master switch to enable/disable webhooks. Example: true
​
webhook_fields.retry
boolean
required
Enable automatic retries for failed webhook deliveries (up to 3 attempts with 15-minute delays). Example: false
​
webhook_fields.events.run.running
boolean
required
Subscribe to run start/resume events. Example: true
​
webhook_fields.events.run.paused
boolean
required
Subscribe to run pause events. Example: false
​
webhook_fields.events.run.done
boolean
required
Subscribe to run completion events. Example: false
​
webhook_fields.events.run.error
boolean
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
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

201
{
  "webhook_fields": {
    "url": "https://your-webhook.com/endpoint",
    "is_active": true,
    "retry": false,
    "events": {
      "run.running": false,
      "run.paused": true,
      "run.done": false,
      "run.error": true
    }
  }
}