Laravel Integration

Laravel Integration – Apify Automation Bridge for PHP Apps

Integrate the Laravel web application framework with the Apify platform to simplify building automation and web scraping APIs. This Actor acts as an integration layer: your Laravel app passes static configuration (webhook URL, API token, queue name) and dynamic scraper parameters, and this Actor runs other Apify Actors, processes integration trigger payloads, and calls back to Laravel with run status and dataset IDs.

Overview

This Laravel Integration Actor connects PHP applications to Apify using static Laravel settings (webhook URL, secrets, queue, correlation ID) and dynamic trigger data (dataset ID, run ID, key-value store ID from integration webhooks). It is built for Laravel developers, backend engineers, and agencies who need a reusable bridge for scraper orchestration, webhook callbacks, and Actor chaining without reimplementing Apify integration logic in every project.

Integration-ready by design: dynamic fields are read from the implicit payload field attached by Apify integration triggers, so users only configure the static Laravel side in most cases.

Key benefits

• Start any Apify scraper from Laravel controllers, jobs, or artisan commands
• Receive progress and completion callbacks on your own HTTPS endpoints
• Chain Actors with Apify Integrations (when a scraper finishes, process its dataset automatically)
• Forward dataset IDs (not full webhook payloads) and optionally preview rows
• Use Apify Proxy and retries for production reliability
• Export integration results in JSON, CSV, or Excel via Apify

Core features

• Run any Actor (mode=run_actor): call targetActorId with targetActorInput from Laravel
• Laravel webhooks: POST callbacks to laravelWebhookUrl with optional HMAC X-Apify-Signature
• Integration triggers: reads payload.resource.defaultDatasetId from Apify integration webhooks automatically
• Process trigger datasets (mode=process_trigger): copy source dataset rows into this run's dataset in batches
• Forward to Laravel (mode=forward_dataset): send dataset metadata (and optional preview) to your app
• Static vs dynamic input: Laravel config is static; trigger fields come from payload or advanced overrides
• Apify Proxy: optional proxyConfiguration merged into child Actor input when mergeProxyIntoTargetActor is true
• Retries: configurable retries for Actor.call() and Laravel webhook HTTP requests
• Health check: runHealthCheckOnStart: true for Apify Console Try actor / CI validation

How to Use Laravel Integration on Apify

Using the Actor

1. Open the Actor on the Apify platform and go to the Input tab.
2. Configure input (see below): set mode, Laravel webhook settings, and either targetActorId + targetActorInput or rely on integration trigger payload.
3. Start the run. The Actor calls child Actors, processes trigger datasets, or forwards results, and pushes summary rows to the default dataset.
4. Open the Dataset tab to browse integration summaries, copied rows, or download JSON/CSV/Excel.
5. Schedule or integrate (optional): connect this Actor on another Actor's Integrations tab, use webhooks, or call from Laravel via apify-client.

Input Configuration

Full schema: INPUT_SCHEMA.json. Example (run Python Scraper from Laravel — no cookies required):

{
  "mode": "run_actor",
  "targetActorId": "sovanza.inc/python-scraper",
  "startUrls": ["https://example.com"],
  "targetActorInput": {
    "startUrls": ["https://example.com"],
    "includeLinks": true,
    "includeHtml": false,
    "exportFormat": "json"
  },
  "laravelWebhookUrl": "https://your-app.test/api/apify/webhook",
  "laravelWebhookSecret": "your-shared-secret",
  "laravelBaseUrl": "https://your-app.test",
  "laravelQueue": "scrapers",
  "correlationId": "job-uuid-from-laravel",
  "waitForFinish": true,
  "waitSecs": 120,
  "pushResultsToLaravel": true,
  "callbackOnProgress": true,
  "mergeProxyIntoTargetActor": false,
  "maxRetries": 3
}

Health-check example (Apify Console Try actor):

{
  "runHealthCheckOnStart": true
}

Integration trigger example (static Laravel config; payload attached automatically):

{
  "mode": "process_trigger",
  "laravelWebhookUrl": "https://your-app.test/api/apify/webhook",
  "laravelQueue": "default",
  "pushResultsToLaravel": true,
  "callbackOnProgress": true
}

• runHealthCheckOnStart (optional): If true, writes one demo dataset row and exits (default false). Use for Apify Console health checks.
• mode (optional): run_actor | process_trigger | forward_dataset (default run_actor).
• laravelWebhookUrl (optional): HTTPS endpoint on your Laravel app for run progress and completion callbacks.
• laravelWebhookSecret (optional): Shared secret for X-Apify-Signature (HMAC SHA-256). Secret input — encrypted at rest, not copied to dataset rows.
• laravelApiToken (optional): Bearer token sent as Authorization when calling your Laravel webhook. Secret input.
• laravelBaseUrl (optional): Base URL of your Laravel app (included in callback payloads for traceability).
• laravelQueue (optional): Queue name your Laravel app should use when dispatching jobs from the webhook (default default).
• correlationId (optional): ID from your Laravel request/job so callbacks can be matched to the originating job.
• targetActorId (required when mode=run_actor): Apify Actor ID or username/actor-name to run (e.g. sovanza.inc/python-scraper).
• startUrls (optional shortcut): Top-level URLs merged into targetActorInput.startUrls for python-scraper.
• targetActorInput (optional): JSON object passed to the target Actor (scraper parameters from Laravel).
• waitForFinish (optional): If true, blocks until the target Actor run completes (default true).
• waitSecs (optional): Max seconds to wait for the target Actor when waitForFinish is true (default 300, max 3600).
• mergeProxyIntoTargetActor (optional): Inject proxyConfiguration into targetActorInput when not already set (default true).
• proxyConfiguration (optional): Apify proxy settings; forwarded to child Actors when merging is enabled.
• maxRetries (optional): Retry count for Actor calls and Laravel webhook requests (default 3).
• retryDelayMs (optional): Base delay between retries in ms (default 1000).
• pushResultsToLaravel (optional): Send final SUCCEEDED callback when the run completes (default true).
• callbackOnProgress (optional): Send STARTED / PROCESSING callbacks during long operations (default true).
• includeDatasetPreviewInCallback (optional): Attach up to maxCallbackItems rows in the final callback (default false).
• maxCallbackItems (optional): Max dataset rows in callback preview (default 50).
• maxDatasetItems (optional): Max source dataset rows to process in process_trigger mode (default 1000).
• datasetBatchSize (optional): Batch size when reading source datasets (default 100).
• sourceDatasetId (advanced): Override dataset ID; when empty, reads payload.resource.defaultDatasetId.
• sourceKeyValueStoreId (advanced): Override KV store ID from trigger payload.
• sourceRunId (advanced): Override triggering run ID from trigger payload.
• payload (automatic): Attached by Apify when started via Actor integrations or isApifyIntegration webhooks.

Authentication & sensitive input

Fields that can hold credentials use Apify secret input (isSecret: true), following the same pattern as other CloudBots Actors:

• laravelWebhookSecret — shared HMAC secret for webhook verification
• laravelApiToken — Bearer token for your Laravel API

Secret values are encrypted in storage and are not written into dataset rows or logs.

Static vs dynamic input (integration-ready)

Per Apify integration guidelines:

• Static input — Laravel webhook URL, secrets, queue, target Actor config (same value every run).
• Dynamic input — dataset ID, run ID, KV store ID from the triggering event (read from payload.resource).

When chained via Integrations → Connect Actor, Apify attaches:

{
  "payload": {
    "eventType": "ACTOR.RUN.SUCCEEDED",
    "resource": {
      "id": "runId...",
      "defaultDatasetId": "datasetId...",
      "defaultKeyValueStoreId": "kvId...",
      "status": "SUCCEEDED"
    }
  }
}

Recommended integration prefill (Apify Console → Actor → Settings → Integrations): see INTEGRATION_INPUT.example.json.

Apify Console (quality score & monetization)

After deploying build 0.1+, finish these in Apify Console → Publication (cannot be set in git):

1. Monetization → Pay per event (PPE) or pay-per-usage — tune based on your CU cost for child Actor calls.
2. Store discounts: enable tier discounts for Bronze, Silver, and Gold plans.
3. Re-run Try actor with runHealthCheckOnStart: true — should finish in under 2 minutes on Apify.

Environment variables (optional)

Variable	Purpose
APIFY_TOKEN	Required on Apify platform; used by Actor.call() and dataset API access for child Actors.
APIFY_LOG_LEVEL	Logging verbosity (default INFO in apify.json).

Run locally

INPUT.json is gitignored. Copy INPUT.example.json to INPUT.json, set APIFY_TOKEN, then:

cd laravel-integration
npm install
cp INPUT.example.json INPUT.json
npm run validate
node src/main.js

Push to Apify:

$apify push

Output

Results are stored in the Actor's default dataset. Each run produces summary rows and, in process_trigger mode, copied data rows.

Typical fields (when data is available):

• Summary: type (health_check, __summary__, __error__), mode, success, timestamp, message, error.
• Child Actor run: targetActorId, runId, status, defaultDatasetId, defaultKeyValueStoreId, itemCount.
• Trigger processing: sourceDatasetId, sourceRunId, outputDatasetId, processedItems.
• Copied rows: original dataset fields plus __sourceDatasetId, __sourceRunId metadata.

Example summary item (illustrative):

{
  "type": "__summary__",
  "mode": "run_actor",
  "success": true,
  "targetActorId": "YOUR_USERNAME/instagram-reels-scraper",
  "runId": "abc123runId",
  "status": "SUCCEEDED",
  "defaultDatasetId": "xyz789datasetId",
  "itemCount": 5,
  "timestamp": "2026-06-04T12:00:00.000Z"
}

Example Laravel callback payload (sent to your webhook, not stored in dataset unless you log it):

{
  "service": "laravel-integration",
  "status": "SUCCEEDED",
  "phase": "completed",
  "correlationId": "uuid-from-laravel",
  "laravelQueue": "scrapers",
  "mode": "run_actor",
  "targetActorId": "YOUR_USERNAME/instagram-reels-scraper",
  "runId": "childRunId",
  "defaultDatasetId": "resultDatasetId",
  "itemCount": 10,
  "apifyDatasetUrl": "https://api.apify.com/v2/datasets/.../items",
  "timestamp": "2026-06-04T12:00:00.000Z"
}

➡️ Output is structured for Laravel jobs, warehouses, or spreadsheet export via Apify.

Use Cases

• Laravel scraping APIs: expose POST /api/scrape/... endpoints that start Apify runs and return run/dataset IDs.
• Queued job pipelines: receive webhooks in Laravel, dispatch jobs to laravelQueue, pull dataset items asynchronously.
• Actor chaining: when a scraper finishes, automatically process or forward its default dataset to your app.
• Multi-tenant SaaS: pass correlationId per customer request and route callbacks to the correct tenant handler.

Integrations & API

• Run and fetch results through the Apify API
• Call from Laravel using apify/apify-client (see routes/laravel_integration.example.php)
• Connect Zapier, Make, Google Sheets, and other Apify integrations
• Webhooks and schedules for recurring automation
• Chain Actors via Integrations → Connect Actor with isApifyIntegration webhooks

Laravel example (PHP)

Install the official client:

$composer require apify/apify-client

Call this Actor from Laravel:

use Apify\Client\ApifyClient;

$client = new ApifyClient(['token' => env('APIFY_TOKEN')]);

$run = $client->actor('YOUR_USERNAME/laravel-integration')->call([
    'mode' => 'run_actor',
    'targetActorId' => 'YOUR_USERNAME/instagram-reels-scraper',
    'targetActorInput' => [
        'usernames' => ['https://www.instagram.com/nasa/'],
        'resultsLimit' => 10,
    ],
    'laravelWebhookUrl' => route('apify.webhook'),
    'laravelWebhookSecret' => env('APIFY_WEBHOOK_SECRET'),
    'correlationId' => (string) Str::uuid(),
    'waitForFinish' => false,
]);

Webhook handler (verify signature):

public function handle(Request $request)
{
    $body = $request->getContent();
    $expected = hash_hmac('sha256', $body, env('APIFY_WEBHOOK_SECRET'));
    abort_unless(hash_equals($expected, $request->header('X-Apify-Signature', '')), 401);

    $payload = json_decode($body, true);
    // status: STARTED | PROCESSING | SUCCEEDED | FAILED | DATASET_READY
}

Setting up Actor integration (webhook chain)

1. Open your scraper Actor → Integrations → Connect Actor
2. Select laravel-integration
3. Event: Run succeeded
4. Static input: Laravel webhook URL, queue, secrets
5. Apify prefills dynamic fields from {{resource.defaultDatasetId}} via payload

See Integrating Actors via API.

Why Choose This Actor?

• Integration-ready — reads payload.resource.defaultDatasetId automatically per Apify guidelines
• Laravel-first callbacks — HMAC signatures, queue hints, correlation IDs
• Run any scraper — one stable integration Actor instead of custom glue per scraper
• Proxy + retries — production patterns reused from CloudBots scraper actors
• Built for Apify datasets, exports, API access, and Actor chaining

FAQ

How does Laravel Integration work?

Your Laravel app starts this Actor with static config and scraper parameters. The Actor calls child Apify Actors via Actor.call(), processes integration trigger datasets in batches, or forwards dataset metadata to your Laravel webhook. Progress and completion are reported via HTTPS POST callbacks.

Can I call scrapers directly from Laravel without this Actor?

Yes. This Actor adds standardized integration trigger handling, webhook callbacks, proxy merging, retries, and dataset batch processing in one reusable place.

Does the webhook include all scraped data?

No. By design, Apify integrations pass dataset IDs, not full dataset contents. Enable includeDatasetPreviewInCallback for a limited preview; otherwise pull items via the Apify API in your Laravel job.

What is the difference between static and dynamic input?

Static input (webhook URL, secrets, queue) stays the same across runs. Dynamic input (dataset ID, run ID) comes from the integration trigger payload field automatically when you connect this Actor on another Actor's Integrations tab.

Can I use this without Laravel?

Yes. Any HTTPS endpoint can receive callbacks; Laravel-specific fields (laravelQueue, laravelBaseUrl) are optional metadata.

What integration modes are available?

• run_actor — start a child scraper with targetActorId + targetActorInput
• process_trigger — copy rows from a trigger dataset into this run's dataset
• forward_dataset — POST dataset metadata to your Laravel webhook

Why did run_actor fail with "does not support running public Actors"?

Some Apify plans cannot call Store/public Actors like apify/hello-world. Options:

• Set runHealthCheckOnStart: true for a quick smoke test (no child Actor).
• Keep useDemoFallbackOnPublicActorError: true (default) — the Actor writes a demo result row instead of failing.
• In production, set targetActorId to your own Actor (e.g. YOUR_USERNAME/instagram-reels-scraper).

What formats can I download?

JSON, CSV, and Excel from the Apify dataset UI, plus full access via the Apify API.

SEO Keywords

laravel apify integration
apify laravel webhook
laravel scraping api
apify actor integration
laravel automation apify
php apify client
web scraping laravel
apify integration actor
laravel queue webhook
apify dataset callback

Actor permissions

This Actor is intended to work with limited permissions: it reads your input, calls other Actors you specify, reads datasets by ID, and writes to its default dataset. It posts callbacks only to URLs you provide.

To set limited permissions in Apify Console:

1. Open your Actor on the Apify platform.
2. Go to Source or Settings.
3. Open Review permissions / Permissions.
4. Choose Limited permissions and save.

Limitations

• Child Actor runs consume your Apify platform credits and depend on the target Actor's reliability.
• waitSecs caps how long this Actor waits for a child run; very long scrapes may need waitForFinish: false and webhook-based completion handling in Laravel.
• Webhook delivery requires your Laravel endpoint to be reachable from Apify cloud.
• Dataset preview in callbacks is limited by maxCallbackItems; large datasets should be fetched via the Apify API in Laravel.
• This Actor orchestrates integration — it does not scrape websites directly unless configured to call a scraper Actor.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Get Started

Configure your Laravel webhook URL, set mode=run_actor with a target scraper, enable proxy if needed, and start your first run on Apify — or connect this Actor on another Actor's Integrations tab to chain scrapers automatically. 🚀