Index of every page on this site: llms.txt
All skills
jeremylongshore avatar

/apify-webhooks-events

@820dfc8
Run it yourself

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 with "apify webhook", "apify events", "actor run notification", "apify run succeeded webhook", "apify ad-hoc webhook".

Use this Skill: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/apify-webhooks-events

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈92 tokens for metadata: the name and description. ≈1.4k when used: this file. ≈1.5k more on demand in 2 files.

Description uses 4.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈368 characters, or 4.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.APIFY_TOKEN) or pass Authorization: Bearer $APIFY_TOKEN 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

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. 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

Issue Cause Solution
Webhook not delivered URL unreachable Verify HTTPS, check firewall
Duplicate processing Webhook retry on non-2xx Implement idempotency
Slow processing Handler takes >30s Respond 200 immediately, process async
Missing data in payload Wrong template vars Check template variable spelling
Webhook disabled Too many failures Re-enable in Console or via API

Resources

Next Steps

For performance optimization, see apify-performance-tuning.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

2 warnings2mo3 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill provides legitimate instructions and code examples for implementing Apify webhooks. It follows security best practices, such as environment-based credential management, and uses official SDKs.

  • Socket2mo

    1 alert: gptAnomaly

  • Snyk2mo

    Risk: MEDIUM · 1 issue

Signed by skilld at 820dfc8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 20 hours ago.

Activeupdated 4 months ago
What it can do
Reads files Edits files Runs commands
version
1.5.0
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
[
  "saas",
  "scraping",
  "automation",
  "apify"
]
All 4 allowed tools
ReadWriteEditBash(curl:*)
Other metadata
compatibility
Designed for Claude Code

README badge

README badge for jeremylongshore/tons-of-skills-marketplace/apify-webhooks-events