How to monitor Apify actor failures, including customer-triggered PPE runs

TL;DR: ApifyForge Monitor sends instant email and Slack alerts when any Apify actor run fails, times out, or is aborted — including customer-triggered PPE runs. One line of code, zero Apify credits, under 30 seconds from failure to alert.

ApifyForge Monitor is a run-level failure alerting service for Apify actors. It sends email and Slack alerts within seconds when any monitored actor run fails, times out, or aborts — including runs triggered by paying PPE customers. It complements Apify's built-in monitoring, which provides aggregate charts and threshold alerts for your own runs, by adding per-run alerting for customer-triggered failures.

Setup takes under 5 minutes. Starter tier covers 3 actors, $9/month for 25, $29/month unlimited. No API token sharing required. According to a 2023 PagerDuty survey, mean time to detect (MTTD) for production incidents averages 4.2 hours without real-time alerting — ApifyForge Monitor reduces this to under 30 seconds for Apify actor failures.

Questions this page answers

• How do I get alerts when an Apify actor run fails?
• Can I monitor customer-triggered PPE runs?
• What is the difference between static and ad-hoc webhooks?
• Does ApifyForge Monitor replace Apify monitoring or Sentry?
• Do I need to share my Apify API token?
• How do I set up failure monitoring in JavaScript and Python?

Key definitions

• Apify actor — A cloud program that runs on the Apify platform, typically used for web scraping, data extraction, or automation.
• PPE (pay-per-event) — A pricing model where customers pay per result delivered, not per compute minute. When a PPE customer's run fails, they get no results and the developer may not know.
• Static webhook — A webhook configured in the Apify Console UI. Fires only for the actor owner's own runs.
• Ad-hoc webhook — A webhook created at runtime inside the actor code using Actor.addWebhook(). Fires for every user's runs, including customer-triggered runs.

Why Apify developers miss customer failures

Apify provides built-in monitoring with aggregate charts, threshold alerts, and status notifications for runs you start yourself. This covers your own testing and development runs well. However, when a paying PPE customer triggers a run that fails, times out, or is aborted, the failure appears only in aggregate 30-day statistics — not as an individual alert to the actor owner.

Without per-run alerting for customer-triggered failures, developers typically discover problems through support tickets or negative Store reviews, often days after the failure occurred. ApifyForge Monitor closes this gap by using ad-hoc webhooks to surface every failure from every user in real time.

Quick comparison: ApifyForge Monitor vs alternatives

Need	Best option
Aggregate charts and threshold alerts for your own runs	Apify built-in monitoring
Per-run alerts for customer-triggered PPE failures	ApifyForge Monitor
Full application traces and exception observability	Sentry or similar APM
All three combined	Use all three — they are complementary

How it works

ApifyForge Monitor uses Apify's ad-hoc webhook mechanism. You add one line of code — Actor.addWebhook() — inside your actor's main function. This registers a webhook on every run, including customer-triggered runs. When a run ends with a FAILED, TIMED_OUT, or ABORTED status, Apify sends the event to ApifyForge, which delivers an alert with the actor name, error message, run ID, and console link.

The key difference from static webhooks configured in the Apify Console: static webhooks fire only for the actor owner's runs. Ad-hoc webhooks created with Actor.addWebhook() fire for every user's runs, which is how ApifyForge Monitor surfaces customer-triggered failures.

Static webhooks vs ad-hoc webhooks for monitoring

Apify supports two webhook types. Static webhooks are configured in the Apify Console and fire only for the actor owner's runs. Ad-hoc webhooks are created at runtime using Actor.addWebhook() and fire for every user's runs. ApifyForge Monitor uses ad-hoc webhooks because they are the mechanism that enables customer-run failure visibility.

Quick setup (under 5 minutes)

Step 1: Sign in to ApifyForge Monitor at apifyforge.com/connect — no credit card required for the Starter tier.

Step 2: Add an Actor.addWebhook() call inside your actor's main function for ACTOR.RUN.FAILED, ACTOR.RUN.TIMED_OUT, and ACTOR.RUN.ABORTED events.

await Actor.addWebhook({
  eventTypes: ['ACTOR.RUN.FAILED', 'ACTOR.RUN.TIMED_OUT', 'ACTOR.RUN.ABORTED'],
  requestUrl: 'https://apifyforge.com/api/webhooks/apify-failures',
  idempotencyKey: `apifyforge-${Actor.getEnv().actorRunId}`,
});

The idempotencyKey prevents duplicate webhooks if the actor restarts mid-run (see Apify ad-hoc webhook docs).

For Python actors:

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}',
)

Step 3: Deploy your actor and trigger a test failure to verify alerts are working. Monitoring is now live for every run.

For the full setup guide with production patterns and testing instructions, see Setup Guide.

Plans and pricing

Plan	Price	Actors	Alerts
Starter	$0/month	3	Email — actor name, status, error, run ID, duration
Developer	$9/month	25	Email + Slack — adds exit code diagnostics, SUCCEEDED monitoring
Pro	$29/month	Unlimited	All of Developer — adds customer user ID, custom integrations

All plans include custom error context via Actor.setStatusMessage(). See full pricing details.

What it does and does not do

ApifyForge Monitor sends real-time per-run alerts for failure events. It does not validate data quality, detect HTML changes, or replace general APM tools like Sentry. For a detailed comparison of ApifyForge Monitor, Apify's built-in monitoring, and Sentry, see ApifyForge Monitor vs Apify Monitoring.

Troubleshooting: not receiving alerts

If you set up ApifyForge Monitor but are not receiving emails, check these items:

1. Monitoring is enabled (toggle switch is on in the dashboard).
2. Notification email is set and saved.
3. The failing actor's ID is in your monitored actors list (exact match required).
4. Webhook URL on the Apify side matches your current ApifyForge URL.
5. Webhook event types include ACTOR.RUN.FAILED, ACTOR.RUN.TIMED_OUT, and ACTOR.RUN.ABORTED.
6. Check spam/junk folders.
7. Test manually: trigger a known failure and check your failure log.

The most common cause is a mismatch between the actor ID in your monitored list and the actId field Apify sends in webhook payloads.

Learn more

• Full setup guide (JS + Python) — production patterns, idempotency, testing
• Customer-run failure alerts explained — why customer PPE failures are easy to miss
• ApifyForge Monitor vs Apify monitoring — detailed comparison
• Slack alerts setup — connect Slack for failure notifications
• Exit codes explained — what codes 91, 137, 143, 255 mean

Frequently asked questions

Does ApifyForge Monitor require my Apify API token?

No. ApifyForge Monitor uses Apify's webhook system. Apify sends failure events to your ApifyForge webhook URL. No API token sharing needed.

How fast are alerts delivered?

ApifyForge processes webhooks and sends alerts within 10 seconds. End-to-end latency from failure to inbox is typically under 30 seconds.

What failure types does it detect?

ApifyForge Monitor tracks 3 failure events: FAILED (exception or crash), TIMED_OUT (exceeded timeout), and ABORTED (manually stopped or platform-killed). Developer and Pro plans also support SUCCEEDED events for SLA tracking.

Can I track which customer triggered a failure?

Yes, on the Pro plan. Each alert includes the Apify user ID of whoever started the run.

What is the difference between static and ad-hoc webhooks for monitoring?

Static webhooks are configured in the Apify Console and fire only for the actor owner's runs. Ad-hoc webhooks are created at runtime using Actor.addWebhook() and fire for every user's runs, including customer-triggered PPE runs. ApifyForge Monitor uses ad-hoc webhooks because they are the mechanism that enables customer-run failure visibility.

What happens if my actor restarts mid-run?

Use an idempotencyKey based on the run ID (e.g., apifyforge-${Actor.getEnv().actorRunId}) to prevent duplicate webhook registrations. If the actor restarts and re-registers the webhook with the same idempotency key, Apify deduplicates it automatically. See the Apify ad-hoc webhook docs for details.

Last updated: March 30, 2026