Skip to content

Commit 500ee51

Browse files
ngut37ngut37
committed
docs: add Windmill documentation
1 parent 30d0148 commit 500ee51

File tree

1 file changed

+216
-0
lines changed
  • sources/platform/integrations/workflows-and-notifications

1 file changed

+216
-0
lines changed

‎sources/platform/integrations/workflows-and-notifications/windmill.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
---
2+
title: Windmill integration
3+
description: Use Windmill to run Apify Actors and Tasks, react to Apify events via webhooks or polling, and move data between Apify and other services with Windmill scripts and flows.
4+
sidebar_label: Windmill
5+
sidebar_position: 8
6+
slug: /integrations/windmill
7+
---
8+
9+
**Use Windmill to run Apify Actors and Tasks, react to Apify events via webhooks or polling, and move data between Apify and other services with Windmill scripts and flows.**
10+
11+
---
12+
13+
[Windmill](https://www.windmill.dev/) is an open-source automation platform for building scripts and flows that connect your tools and data. With the Apify integration for Windmill, you can run Actors and Tasks, scrape websites, extract data from storage, and trigger workflows based on Apify events.
14+
15+
This guide shows you how to install the Apify package, set up authentication, and create automated workflows that integrate with Apify.
16+
17+
## Prerequisites
18+
19+
Before you begin, make sure you have:
20+
21+
- An [Apify account](https://console.apify.com/)
22+
- A [Windmill instance](https://www.windmill.dev/docs/getting_started/how_to_use_windmill) (self-hosted or cloud)
23+
24+
## Install the Apify integration
25+
26+
The Apify integration provides scripts, flows, and resources that will be available through the Windmill Hub.
27+
28+
<!-- SCREENSHOT: Windmill Hub showing available integrations including Apify alongside with other integrations -->
29+
30+
### Step 1: Import Apify scripts from Windmill Hub
31+
32+
You can import Apify integration scripts into your flows from the Windmill Hub, regardless of whether you're using Windmill Cloud or a self-hosted instance. The following components will be available:
33+
34+
**Scripts (Actions):**
35+
36+
- Run Actor
37+
- Run Task
38+
- Scrape Single URL
39+
- Get Dataset Items
40+
- Get Key-Value Store
41+
42+
**Scripts (Triggers):**
43+
44+
- Polling-based Actor Run Trigger
45+
- Polling-based Task Trigger
46+
47+
**Flows (Triggers):**
48+
49+
- Webhook-based Actor Trigger
50+
- Webhook-based Task Trigger
51+
52+
**Resources:**
53+
54+
- Apify Auth Resource (for storing your API token)
55+
- Webhook Config Resource (optional, for managing webhook-based triggers)
56+
57+
<!-- SCREENSHOT: Windmill Hub showing available integrations including Apify -->
58+
<!-- SCREENSHOT: Importing Apify scripts from Windmill Hub -->
59+
60+
### Step 2: Authentication
61+
62+
You can provide the token to scripts via a **Windmill Resource**. Create it either in the **Resources** tab or directly from a script.
63+
64+
#### Option A — Create in the Resources tab
65+
66+
1. Open **Resources** → **New Resource**.
67+
2. Select `apify_api_key` resource type.
68+
3. Name it (e.g., `apify_token`) and paste your Apify API token.
69+
4. Save, then reference this resource in your scripts/flows.
70+
71+
<!-- SCREENSHOT: from readme -->
72+
73+
#### Option B — Create/bind from a script
74+
75+
1. Open the script in Windmill UI.
76+
2. Add a secret input parameter (e.g., `apify_token`) .
77+
3. Bind it to the resource you created (or create a new one inline).
78+
4. Use the bound token inside the script to call Apify.
79+
80+
<!-- SCREENSHOT: from readme -->
81+
82+
## Create your first workflow
83+
84+
Let's create a simple workflow that runs an Actor and fetches its results.
85+
86+
### Step 1: Create a new flow
87+
88+
1. In the Windmill UI, click **New Flow**.
89+
2. Give your flow a descriptive name (e.g., "Run Actor and Get Results").
90+
91+
### Step 2: Add the Run Actor script
92+
93+
1. Click **Add Step** and search for "Run Actor".
94+
2. Select the **Run Actor** script.
95+
3. Configure the inputs:
96+
- **Apify Auth**: Select your `apify_token` resource
97+
- **Actor ID or Slug**: Enter the Actor you want to run
98+
- **Input**: JSON input for the Actor (optional)
99+
- **Wait for Finish**: Set to `true` to wait for completion
100+
- **Memory**: Memory allocation in MB (optional)
101+
- **Timeout**: Timeout in seconds (optional)
102+
103+
<!-- SCREENSHOT: Run Actor script configuration form -->
104+
105+
### Step 3: Add the Get Dataset Items script
106+
107+
1. Add another step and search for "Get Dataset Items".
108+
2. Configure the inputs:
109+
- **Apify Auth**: Select your `apify_token` resource
110+
- **Dataset ID**: Use the `defaultDatasetId` from the previous step
111+
- **Limit**: Number of items to retrieve (optional)
112+
113+
<!-- SCREENSHOT: Get Dataset Items script configuration -->
114+
<!-- SCREENSHOT: Flow showing both scripts connected -->
115+
116+
### Step 4: Test and run
117+
118+
1. Click **Test** to run the flow with sample data.
119+
2. Review the results and ensure both steps completed successfully.
120+
3. Save and activate your flow.
121+
122+
<!-- SCREENSHOT: Flow execution results showing successful completion -->
123+
124+
## Use webhooks to trigger workflows
125+
126+
Windmill provides webhook-based triggers that can automatically start workflows when Apify events occur.
127+
128+
### Step 1: Create a webhook-triggered flow
129+
130+
1. Create a new flow and add the **Webhook-based Actor Trigger** script.
131+
2. Configure the webhook:
132+
- **Apify Auth**: Select your `apify_token` resource
133+
- **Actor ID**: Select the Actor to monitor
134+
- **Event Types**: Choose events (e.g., `succeeded`, `failed`)
135+
- **Webhook URL**: Copy the webhook URL from the script's trigger section
136+
137+
<!-- SCREENSHOT: Webhook trigger configuration -->
138+
<!-- SCREENSHOT: Webhook URL display in trigger section -->
139+
140+
### Step 2: Register the webhook in Apify
141+
142+
1. Go to your Actor's **Integrations** tab in Apify Console.
143+
2. Click **Add Integration** → **Webhook**.
144+
3. Enter the webhook URL from Windmill.
145+
4. Select the event types you want to monitor.
146+
5. Save the webhook.
147+
148+
<!-- SCREENSHOT: Apify Console webhook configuration -->
149+
<!-- SCREENSHOT: Webhook integration setup form -->
150+
151+
### Step 3: Test the webhook
152+
153+
1. Run your Actor in Apify Console.
154+
2. When the Actor finishes, the webhook should trigger your Windmill flow automatically.
155+
3. Check the flow execution logs to verify the trigger worked.
156+
157+
<!-- SCREENSHOT: Flow execution triggered by webhook -->
158+
<!-- SCREENSHOT: Execution logs showing webhook payload -->
159+
160+
## Available operations
161+
162+
The Apify integration provides several operations you can use in your Windmill workflows.
163+
164+
### Actions (Scripts)
165+
166+
**Run Actor**
167+
168+
- Starts an Actor with optional input and configuration
169+
- Can wait for completion or run asynchronously
170+
- Returns run metadata including dataset ID
171+
172+
**Run Task**
173+
174+
- Executes a predefined Actor task
175+
- Similar to Run Actor but uses task configuration
176+
- Ideal for recurring operations
177+
178+
**Scrape Single URL**
179+
180+
- Runs a lightweight scraper for a single webpage
181+
- Returns content as text, markdown, and HTML
182+
- Perfect for quick content extraction
183+
184+
**Get Dataset Items**
185+
186+
- Retrieves items from a dataset
187+
- Can filter by dataset ID or last run
188+
- Supports pagination and item limits
189+
190+
**Get Key-Value Store**
191+
192+
- Reads values from key-value stores
193+
- Can retrieve specific keys or list all keys
194+
- Useful for configuration and state management
195+
196+
### Triggers
197+
198+
**Webhook-based Triggers**
199+
200+
- **Actor Webhook Trigger**: Responds to Actor run events
201+
- **Task Webhook Trigger**: Responds to task run events
202+
- Real-time event processing with full payload data
203+
204+
**Polling-based Triggers**
205+
206+
- **Actor Run Polling Trigger**: Periodically checks for new Actor runs
207+
- **Task Run Polling Trigger**: Periodically checks for new task runs
208+
- Fallback option when webhooks aren't available
209+
210+
## Resources
211+
212+
- [Windmill Documentation](https://www.windmill.dev/docs)
213+
- [Windmill Local Development](https://www.windmill.dev/docs/advanced/local_development)
214+
- [Apify API Documentation](https://docs.apify.com)
215+
- [Apify Webhooks](https://docs.apify.com/webhooks)
216+
- [Apify Actors & Tasks](https://docs.apify.com/actors)

0 commit comments

Comments
 (0)