Skip to content
Delivery

Configure Webhook Delivery

Set up real-time webhook notifications for squid run events

The v1 API, for batchesSquids, tasks and runs: many calls on a schedule, delivered where you work. For one call that answers in seconds, use the API v2.
POSThttps://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

Authorizationstringheaderrequired

Your API authentication token. Value: Token YOUR_API_KEY

Content-Typestringheaderrequired

Must be application/json. Value: application/json

Query Parameters

squidstringqueryrequired

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

Request Body

webhook_fields.urlstringrequired

Your webhook endpoint URL that will receive POST requests. Example: "https://your-webhook.com/endpoint"

webhook_fields.is_activebooleanrequired

Master switch to enable/disable webhooks. Example: true

webhook_fields.retrybooleanrequired

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

webhook_fields.events.run.runningbooleanrequired

Subscribe to run start/resume events. Example: true

webhook_fields.events.run.pausedbooleanrequired

Subscribe to run pause events. Example: false

webhook_fields.events.run.donebooleanrequired

Subscribe to run completion events. Example: false

webhook_fields.events.run.errorbooleanrequired

Subscribe to run error events. Example: true

Response Field Explanations

webhook_fields.urlstring

Configured webhook endpoint URL. Example: "https://your-webhook.com/endpoint"

webhook_fields.is_activeboolean

Whether webhooks are active. Example: true

webhook_fields.retryboolean

Whether retry mechanism is enabled. Example: false

webhook_fields.events.run.runningboolean

Subscription status for run.running events. Example: true

webhook_fields.events.run.pausedboolean

Subscription status for run.paused events. Example: false

webhook_fields.events.run.doneboolean

Subscription status for run.done events. Example: false

webhook_fields.events.run.errorboolean

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": true,
      "run.paused": false,
      "run.done": false,
      "run.error": true
    }
  }
}