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.

Prerequisites

• npm install apify-client in your project (and express if you build an HTTP handler)
• An API token in APIFY_TOKEN — read it from the environment

(process.env.APIFYTOKEN) or pass Authorization: Bearer $APIFYTOKEN on REST

calls, never hard-code it

• A public HTTPS endpoint for Apify to POST to (use ngrok while developing)
• Familiarity with apify-sdk-patterns

Event Types

Instructions

Step 1: Create a Persistent Webhook

Persistent webhooks fire for every run of an Actor. Set condition.actorId, list

the eventTypes you care about, and shape the delivered body with

payloadTemplate:

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });

const webhook = await client.webhooks().create({
  eventTypes: ['ACTOR.RUN.SUCCEEDED', 'ACTOR.RUN.FAILED', 'ACTOR.RUN.TIMED_OUT'],
  condition: { actorId: 'YOUR_ACTOR_ID' },
  requestUrl: 'https://your-app.com/api/webhooks/apify',
  payloadTemplate: JSON.stringify({
    eventType: '{{eventType}}',
    actorRunId: '{{actorRunId}}',
    defaultDatasetId: '{{resource.defaultDatasetId}}',
    status: '{{resource.status}}',
    statusMessage: '{{resource.statusMessage}}',
  }),
  isAdHoc: false,
});

console.log(`Webhook created: ${webhook.id}`);

The full payload template (all run fields) and the complete variable table are in

payload templates & local testing.

Step 2: Use Ad-Hoc Webhooks for Single Runs

Ad-hoc webhooks are created at run time and fire only for that specific run — pass

a webhooks array when starting the Actor:

const run = await client.actor('username/my-actor').start(
  { startUrls: [{ url: 'https://example.com' }] },
  {
    webhooks: [{
      eventTypes: ['ACTOR.RUN.SUCCEEDED', 'ACTOR.RUN.FAILED'],
      requestUrl: 'https://your-app.com/api/webhooks/apify',
    }],
  },
);

The equivalent REST/curl form is in payload templates & local testing.

Step 3: Handle the Webhook

Your endpoint must return a 2xx within 30 seconds, so acknowledge immediately and

process asynchronously. On SUCCEEDED, fetch the dataset via defaultDatasetId; on

FAILED/TIMED_OUT, pull the run log and alert:

app.post('/api/webhooks/apify', async (req, res) => {
  res.status(200).json({ received: true }); // ack first
  try {
    await processWebhook(req.body); // switch on eventType, fetch dataset, alert
  } catch (error) {
    console.error('Webhook processing failed:', error);
  }
});

The full processWebhook switch (dataset fetch, log tail, oncall alerting) is in

full implementation.

Step 4: Make Processing Idempotent, Chain Pipelines, and Manage Webhooks

Apify may deliver a webhook more than once, so dedupe on

${actorRunId}:${eventType} before doing work. You can also chain Actors (Stage 1

SUCCEEDED → start Stage 2) and manage the webhook lifecycle (list, update,

delete, inspect dispatches). All three patterns — idempotent processing,

event-driven pipeline, and lifecycle management — are in

full implementation.

Output

• A created webhook returns its id (persistent webhooks are visible under

client.webhooks().list(); ad-hoc webhooks are scoped to one run)

• On each matching event, Apify POSTs the rendered payloadTemplate JSON to your

requestUrl

• client.webhook(id).dispatches().list() returns the delivery history — each entry

carries a status, createdAt, and the endpoint's responseStatus so you can

confirm delivery or diagnose retries

Examples

• Persistent + ad-hoc webhook creation — Steps 1 and 2 above
• Full handler, idempotency, pipeline chaining, lifecycle management — full implementation
• Payload template variables, REST/curl creation, and local testing with ngrok — payload templates & local testing

Error Handling

Resources

• Webhook Event Types
• Webhook Actions
• Ad-Hoc Webhooks

Next Steps

For performance optimization, see apify-performance-tuning.