How to set up the Apify actor failure monitor

The Failure Monitor gives you real-time email alerts when your Apify actors fail, time out, or abort. Unlike the Failures dashboard which shows aggregated deltas between snapshots, the Monitor uses Apify webhooks to notify you the moment a failure happens — no polling, no waiting for a daily report.

Plans and pricing

The Monitor is available to all signed-in users. The free plan lets you monitor up to 3 actors. The Developer plan ($9/month) supports 25 actors, and the Pro plan ($29/month) supports unlimited actors.

How it works

When you enable monitoring, ApifyForge generates a unique webhook URL tied to your account. This URL contains a 256-bit secret token that identifies you. You then register this URL as a webhook on your Apify actors — either through the Apify Console or by adding a code snippet to your actor source. When any of those actors fails, Apify sends a POST request to your webhook URL. ApifyForge receives the webhook, verifies your identity via the token, checks that the failing actor is in your monitored actors list, stores the failure in your account, and sends you an email alert with the actor name, error message, run duration, and a direct link to the failed run in the Apify Console.

Security model

Your webhook URL is unique to your account — nobody else can trigger alerts on your behalf. The monitored actors list acts as an allowlist: even if someone registers your webhook URL on 100 actors, only failures from actors you have explicitly listed will be processed. Everything else is silently dropped. This means your free plan limit of 3 actors is enforced at the webhook processing level, not just the UI. You cannot game the limit by registering more webhooks than your plan allows.

Setup guide

Step 1: Go to the dashboard sidebar and click Monitor under Operations. Click Enable Free Monitoring to create your subscription. You will see your unique webhook URL.

Step 2: Enter the Apify actor IDs for up to 3 actors you want to monitor (see Finding your actor ID below).

Step 3: Set your notification email address where alerts should be sent.

Step 4: Register webhooks on your Apify actors using one of the two methods below.

Registering webhooks — Option 1: Apify Console (recommended)

Go to console.apify.com, navigate to your actor, click Settings, then Webhooks, and create a new webhook. Set the event types to ACTOR.RUN.FAILED, ACTOR.RUN.TIMED_OUT, and ACTOR.RUN.ABORTED. Set the Actor filter to your actor's ID. Paste your ApifyForge webhook URL as the request URL. Repeat for each actor you want to monitor.

Registering webhooks — Option 2: Inside your actor code

Add webhook registration directly in your actor code by calling Actor.addWebhook() at the start of your actor's main function. The Monitor dashboard shows the exact code snippet with your webhook URL pre-filled so you can copy and paste it. This method registers the webhook on every run, so it works automatically for new deployments.

Finding your actor ID

The actor ID is the identifier you see in your Apify Console URL when viewing an actor: console.apify.com/actors/YOUR_ACTOR_ID. It can be in slug format like username~my-actor-name or a raw alphanumeric ID like a1B2c3D4e5F6g7.

You can also find actor IDs through the Apify API by calling GET https://api.apify.com/v2/acts?my=true&token=YOUR_TOKEN — the response includes an id field for each actor. Or use the ApifyForge Fleet dashboard: click any actor and copy the actor ID from the detail view.

The actor ID must match exactly what Apify sends in webhook payloads. Common mistakes include using the actor name instead of the ID, adding extra spaces, or using the run ID instead of the actor ID. Organization actors use the org prefix: org-name~actor-name.

Failure log

The Monitor dashboard shows a log of all recorded failures for your account. Each entry includes the actor name, failure status (FAILED, TIMED_OUT, or ABORTED), error message, run duration, timestamp, and a clickable link to the run in the Apify Console. Use this log to spot patterns — for example, if the same actor fails every day at the same time, it might be hitting a rate limit.

Actor limits and enforcement

Each plan has a strict actor limit enforced server-side. When you try to save more actor IDs than your plan allows, the save is rejected entirely — it does not partially save. The limit is also enforced at the webhook processing level: even if you register your webhook URL on 50 actors, only failures from actors in your saved list will be processed.

Duplicate actor IDs are automatically deduplicated before counting against your limit. To change which actors you monitor, simply replace an existing ID with a new one — changes take effect immediately.

Secret rotation

You can rotate your webhook secret at any time from the Monitor dashboard. This instantly invalidates the old webhook URL and generates a new one. After rotating, you must update the URL on all your Apify actors. This is useful if you suspect your URL has been leaked.

Pause and resume

Toggle the enable/disable switch on the Monitor dashboard to pause monitoring without deleting your configuration. When paused, incoming webhooks are silently dropped but your actor list, email, and webhook URL are preserved.

Monitor vs Failures dashboard

The Failures dashboard runs the Failure Tracker actor on demand ($0.10 per report) and compares snapshots of your public run stats. It catches failures from all users who run your actors, but only when you manually trigger a report. The Monitor uses real-time webhooks — you get an email within seconds. However, the Monitor only catches failures on runs where the webhook is registered. For comprehensive coverage, use both: the Monitor for real-time alerts on critical actors, and the Failures dashboard for periodic full-fleet reviews.

Troubleshooting: not receiving email alerts

If you have set up the Monitor but are not receiving emails, check these in order:

1. Monitoring is enabled (toggle switch is on).
2. Notification email is set and saved.
3. The failing actor is in your monitored actors list (exact ID match required).
4. Webhook URL on the Apify side matches your current ApifyForge URL (check after secret rotation).
5. Webhook event types include ACTOR.RUN.FAILED, ACTOR.RUN.TIMED_OUT, and ACTOR.RUN.ABORTED.
6. Check spam/junk folders — add the sender to your contacts.
7. Test manually: trigger a known failure and check if it appears in your failure log. If it appears but no email arrives, the issue is email delivery. If it does not appear, the webhook is misconfigured on the Apify side.

The most common root cause is a mismatch between the actor ID in your monitored list and the actId in the webhook payload.