How to Set Up Apify Actor Failure Monitoring

To set up Apify actor failure monitoring, add a single Actor.addWebhook() call inside your actor's main function and deploy. ApifyForge Monitor receives the webhook on every FAILED, TIMED_OUT, and ABORTED event and sends you an email or Slack alert within seconds. This guide covers the full setup for both JavaScript and Python actors, including production patterns and testing.

Prerequisites

You need an Apify account (free tier works), an actor deployed on the Apify platform, and an ApifyForge Monitor account (sign up free at apifyforge.com/connect). No additional SDKs or packages need to be installed — Actor.addWebhook() is built into the Apify SDK.

JavaScript setup (TypeScript)

Add the webhook registration call at the top of your Actor.main() block, before any other logic. This ensures the webhook is registered even if the actor crashes early.

import { Actor } from 'apify';

Actor.main(async () => {
  // Register failure webhook FIRST — before any logic that might fail
  await Actor.addWebhook({
    eventTypes: [
      'ACTOR.RUN.FAILED',
      'ACTOR.RUN.TIMED_OUT',
      'ACTOR.RUN.ABORTED',
    ],
    requestUrl: 'https://apifyforge.com/api/webhooks/apify-failures',
  });

  // Your actor logic below
  const input = await Actor.getInput();
  // ...
});

The Actor.addWebhook() call is a free Apify API call. It does not consume platform credits, does not increase run duration, and does not require additional memory.

Python setup

Python actors use the Actor.add_webhook() method with snake_case naming. Include an idempotency_key to prevent duplicate webhooks if the actor restarts mid-run.

from apify import Actor

async def main():
    async with Actor:
        # Register failure webhook FIRST
        await Actor.add_webhook(
            event_types=[
                "ACTOR.RUN.FAILED",
                "ACTOR.RUN.TIMED_OUT",
                "ACTOR.RUN.ABORTED",
            ],
            request_url="https://apifyforge.com/api/webhooks/apify-failures",
            idempotency_key=f"apifyforge-{Actor.config.actor_run_id}",
        )

        # Your actor logic below
        actor_input = await Actor.get_input()
        # ...

The idempotency_key parameter prevents duplicate webhook registrations. If the actor process restarts (common with memory-intensive actors), the key ensures only one webhook exists per run. See the Apify ad-hoc webhook documentation for details.

Where to place the webhook call

Place the Actor.addWebhook() call as the very first operation inside your main function, before input parsing, before crawler initialization, and before any network requests. This matters because:

• If your actor crashes during input validation, you still want the failure alert
• If the actor runs out of memory during crawling, the webhook was already registered
• If a customer passes invalid input that causes an immediate error, you see it

Actor.main(async () => {
  // 1. Register webhook (always first)
  await Actor.addWebhook({ /* ... */ });

  // 2. Parse input
  const input = await Actor.getInput();

  // 3. Initialize crawler / make requests
  // 4. Process results
  // 5. Push to dataset
});

Adding custom error context with setStatusMessage

Use Actor.setStatusMessage() at each step of your actor's logic. When the actor fails, the most recent status message appears in your failure alert, giving you immediate context.

await Actor.setStatusMessage('Fetching search results from API');
const results = await fetchApi(query);

await Actor.setStatusMessage(`Processing ${results.length} results`);
for (const result of results) {
  await processResult(result);
}

await Actor.setStatusMessage(`Pushing ${results.length} results to dataset`);
await Actor.pushData(results);

If the actor fails during the API fetch, your alert shows "Fetching search results from API" — so you know exactly where it stopped.

Monitoring SUCCEEDED events for SLA tracking

Add ACTOR.RUN.SUCCEEDED to your eventTypes array to get notified when runs complete successfully. This is useful for SLA tracking, confirming critical pipeline runs, and verifying high-value customer runs.

await Actor.addWebhook({
  eventTypes: [
    'ACTOR.RUN.FAILED',
    'ACTOR.RUN.TIMED_OUT',
    'ACTOR.RUN.ABORTED',
    'ACTOR.RUN.SUCCEEDED',  // Also track successes
  ],
  requestUrl: 'https://apifyforge.com/api/webhooks/apify-failures',
});

Success monitoring is available on Developer ($9/month) and Pro ($29/month) plans.

Error handling around the webhook call

The webhook registration itself can fail (network issues, temporary Apify API outage). Wrap it in a try-catch so your actor still runs even if the monitoring setup fails.

Actor.main(async () => {
  try {
    await Actor.addWebhook({
      eventTypes: ['ACTOR.RUN.FAILED', 'ACTOR.RUN.TIMED_OUT', 'ACTOR.RUN.ABORTED'],
      requestUrl: 'https://apifyforge.com/api/webhooks/apify-failures',
    });
  } catch (err) {
    console.warn('ApifyForge Monitor webhook registration failed:', err.message);
    // Actor continues running — monitoring is best-effort, not blocking
  }

  // Your actor logic continues regardless
  const input = await Actor.getInput();
  // ...
});

Testing your webhook

After deploying, trigger a test failure to verify alerts are working:

1. Run your actor with input that causes a known failure (invalid URL, missing required field)
2. Check your email (or Slack on Developer/Pro plans) for the failure alert
3. Verify the alert contains the actor name, error message, and run link
4. Click the run link to confirm it opens the correct run in the Apify console

You can also check your ApifyForge Monitor dashboard at apifyforge.com/dashboard/monitor to see all received events.

For information on what exit codes mean in your alerts, see Exit Codes Explained. For Slack integration setup, see Slack Alerts.

Last updated: March 2026