Implement Apify webhooks for Actor run notifications and event-driven pipelines.
Use when setting up run completion alerts, building event-driven scraping pipelines,
or configuring ad-hoc webhooks for individual runs.
Trigger: "apify webhook", "apify events", "actor run notification",
"apify run succeeded webhook", "apify ad-hoc webhook".
Implement Apify webhooks for Actor run notifications and event-driven pipelines.
Use when setting up run completion alerts, building event-driven scraping pipelines,
or configuring ad-hoc webhooks for individual runs.
Trigger: "apify webhook", "apify events", "actor run notification",
"apify run succeeded webhook", "apify ad-hoc webhook".
allowed-tools
Read, Write, Edit, Bash(curl:*)
version
1.0.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
["saas","scraping","automation","apify"]
compatible-with
claude-code
Apify Webhooks & Events
Overview
Configure webhooks to receive notifications when Actor runs complete, fail, or time out. Apify supports both persistent webhooks (for all runs of an Actor) and ad-hoc webhooks (for a single run). Event-driven architecture is the recommended pattern for production Apify integrations.
Event Types
Event
Fired When
ACTOR.RUN.CREATED
A new Actor run starts
ACTOR.RUN.SUCCEEDED
Run finishes with SUCCEEDED status
ACTOR.RUN.FAILED
Run finishes with FAILED status
ACTOR.RUN.ABORTED
Run is manually or programmatically aborted
ACTOR.RUN.TIMED_OUT
Run exceeds its timeout
ACTOR.RUN.RESURRECTED
A finished run is resurrected
Instructions
Step 1: Create a Persistent Webhook
Persistent webhooks fire for every run of an Actor:
// List all webhooksconst { items: webhooks } = await client.webhooks().list();
webhooks.forEach(wh => {
console.log(`${wh.id} | ${wh.eventTypes.join(',')} | ${wh.requestUrl}`);
});
// Update a webhookawait client.webhook('WEBHOOK_ID').update({
requestUrl: 'https://new-url.com/webhook',
isEnabled: true,
});
// Delete a webhookawait client.webhook('WEBHOOK_ID').delete();
// Get webhook dispatch history (see delivery attempts)const { items: dispatches } = await client
.webhook('WEBHOOK_ID')
.dispatches()
.list();
dispatches.forEach(d => {
console.log(`${d.status} | ${d.createdAt} | HTTP ${d.responseStatus}`);
});
Webhook Payload Template Variables
Variable
Description
{{eventType}}
Event type string
{{eventData}}
Full event data object
{{createdAt}}
Event creation timestamp
{{actorId}}
Actor ID
{{actorRunId}}
Run ID
{{actorTaskId}}
Task ID (if run from a task)
{{resource.*}}
Any field from the run object
Testing Webhooks Locally
# Use ngrok to expose local server
ngrok http 3000
# Copy the HTTPS URL# Create a test webhook pointing to ngrok# Then trigger a run to see the webhook fire# Or manually simulate a webhook payload
curl -X POST http://localhost:3000/api/webhooks/apify \
-H "Content-Type: application/json" \
-d '{
"eventType": "ACTOR.RUN.SUCCEEDED",
"actorRunId": "test-run-123",
"defaultDatasetId": "test-dataset-456",
"status": "SUCCEEDED"
}'
