Skip to content

Commit a23a8b5

Browse files
committed
docs: keep webhook migration only in v4 guide
The webhook section that landed in `upgrading_to_v3.md` in 24a6fa8 described an intermediate API (`WebhookCreate` + `WebhookCondition`) that never shipped publicly. Move the migration story entirely into `upgrading_to_v4.md` and frame it against the actually-released v3.x `Webhook` class: response fields dropped, `ignore_ssl_errors` / `do_not_retry` / `idempotency_key` kwargs on `Actor.add_webhook` moved onto the `Webhook` model, and `WebhookCondition` removed.
1 parent 34391b7 commit a23a8b5

2 files changed

Lines changed: 15 additions & 70 deletions

File tree

‎docs/04_upgrading/upgrading_to_v3.md‎

Lines changed: 0 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -67,41 +67,6 @@ Some changes in the related model classes:
6767
- `stats` field in `RequestQueueMetadata` - removed as it was unused.
6868
- `RequestQueueHead` - replaced by `RequestQueueHeadWithLocks`.
6969

70-
## Webhook model changes
71-
72-
The SDK no longer ships its own `Webhook` Pydantic model. The webhook models from `apify-client` are now used directly:
73-
74-
- `apify.Webhook` is now an alias of `apify_client._models.WebhookRepresentation`. It still has the same shape used in `Actor.start`, `Actor.call`, and `Actor.call_task` (`event_types`, `request_url`, `payload_template`, `headers_template`).
75-
- `Actor.add_webhook` now accepts an `apify.WebhookCreate` instance instead of `apify.Webhook` + separate kwargs. All fields (`ignore_ssl_errors`, `do_not_retry`, `idempotency_key`, `headers_template`, etc.) move onto the `WebhookCreate` instance. `condition` is required by the underlying type — pass `WebhookCondition()` when you do not need to scope to other resources.
76-
77-
**Before (v2.x):**
78-
79-
```python
80-
from apify import Actor, Webhook
81-
82-
await Actor.add_webhook(
83-
Webhook(event_types=['ACTOR.RUN.FAILED'], request_url='https://example.com'),
84-
idempotency_key='my-key',
85-
)
86-
```
87-
88-
**Now (v3.0):**
89-
90-
```python
91-
from apify import Actor, WebhookCondition, WebhookCreate
92-
93-
await Actor.add_webhook(
94-
WebhookCreate(
95-
event_types=['ACTOR.RUN.FAILED'],
96-
request_url='https://example.com',
97-
condition=WebhookCondition(),
98-
idempotency_key='my-key',
99-
)
100-
)
101-
```
102-
103-
`WebhookCondition`, `WebhookCreate`, `WebhookRepresentation`, `WebhookEventType`, and `ActorPermissionLevel` are all re-exported from `apify` for convenience.
104-
10570
## Removed Actor.config property
10671
- `Actor.config` property has been removed. Use `Actor.configuration` instead.
10772

‎docs/04_upgrading/upgrading_to_v4.md‎

Lines changed: 15 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -12,31 +12,22 @@ Support for Python 3.10 has been dropped. The Apify Python SDK v4.x now requires
1212

1313
## Webhook API simplified
1414

15-
The webhook API has been unified behind a single SDK-level `Webhook` class. The low-level client models that v3 re-exported (`WebhookCreate`, `WebhookCondition`, `WebhookRepresentation`) are no longer part of the public `apify` namespace.
15+
The `Webhook` model has been slimmed down to only the fields a user actually sets when defining a webhook. Server-populated response fields (`id`, `created_at`, `modified_at`, `user_id`, `is_ad_hoc`, `condition`, `last_dispatch`, `stats`) and the unused `WebhookCondition` helper class have been removed from the public namespace. The retry and idempotency kwargs that used to live on `Actor.add_webhook` have moved onto the `Webhook` instance itself, so a single object captures the full webhook definition.
1616

17-
The public `apify` namespace now exposes only:
17+
### `Actor.add_webhook` — kwargs moved onto `Webhook`
1818

19-
- `apify.Webhook` — a new SDK-level model covering both ad-hoc (`Actor.start` / `Actor.call`) and persistent (`Actor.add_webhook`) use cases.
20-
- `apify.WebhookEventType` — unchanged.
21-
22-
`apify.WebhookCondition`, `apify.WebhookCreate`, `apify.WebhookRepresentation`, and `apify.ActorPermissionLevel` have been removed from the public namespace. If you still need them, import directly from `apify_client._models` / `apify_client._literals`.
23-
24-
### `Actor.add_webhook`
25-
26-
`Actor.add_webhook` now takes the new `Webhook` instance directly. The `condition` argument is gone — the SDK automatically binds the webhook to the current Actor run.
19+
`ignore_ssl_errors`, `do_not_retry`, and `idempotency_key` were previously kwargs on `Actor.add_webhook`. In v4 they are fields on the `Webhook` model.
2720

2821
**Before (v3.x):**
2922

3023
```python
31-
from apify import Actor, WebhookCondition, WebhookCreate
24+
from apify import Actor, Webhook
3225

3326
await Actor.add_webhook(
34-
WebhookCreate(
35-
event_types=['ACTOR.RUN.FAILED'],
36-
request_url='https://example.com',
37-
condition=WebhookCondition(),
38-
idempotency_key='my-key',
39-
)
27+
Webhook(event_types=['ACTOR.RUN.FAILED'], request_url='https://example.com'),
28+
ignore_ssl_errors=False,
29+
do_not_retry=False,
30+
idempotency_key='my-key',
4031
)
4132
```
4233

@@ -49,33 +40,22 @@ await Actor.add_webhook(
4940
Webhook(
5041
event_types=['ACTOR.RUN.FAILED'],
5142
request_url='https://example.com',
43+
ignore_ssl_errors=False,
44+
do_not_retry=False,
5245
idempotency_key='my-key',
5346
)
5447
)
5548
```
5649

57-
### `idempotency_key` kwarg on `Actor.add_webhook` is deprecated
58-
59-
The v2-style `Actor.add_webhook(webhook, idempotency_key=...)` form still works but emits a `DeprecationWarning` and will be removed in v5.0.0. Set `idempotency_key` on the `Webhook` instance instead.
60-
61-
### Ad-hoc webhooks on `Actor.start` / `Actor.call` / `Actor.call_task`
62-
63-
The `webhooks` argument on these methods still accepts a `list[Webhook]`, but `Webhook` is now the new SDK class rather than an alias for `WebhookRepresentation`. The accepted fields (`event_types`, `request_url`, `payload_template`, `headers_template`) are unchanged, so most call sites just need to update the import.
50+
The `idempotency_key` kwarg form on `Actor.add_webhook` still works for one more release but emits a `DeprecationWarning` and will be removed in v5.0.0. The `ignore_ssl_errors` and `do_not_retry` kwargs have been removed outright — set them on the `Webhook` instance.
6451

65-
**Before (v3.x):**
66-
67-
```python
68-
from apify import Actor, Webhook
52+
### `WebhookCondition` removed from public namespace
6953

70-
await Actor.start(
71-
'some-actor-id',
72-
webhooks=[Webhook(event_types=['ACTOR.RUN.SUCCEEDED'], request_url='https://example.com')],
73-
)
74-
```
54+
`apify.WebhookCondition` is no longer exported. It was only used as a placeholder argument to `Actor.add_webhook`; the SDK now binds the webhook to the current Actor run internally, so you do not need to construct a condition at all.
7555

76-
**Now (v4.0):**
56+
### Ad-hoc webhooks on `Actor.start` / `Actor.call` / `Actor.call_task`
7757

78-
Same code — only the underlying class has changed. The import path remains `from apify import Webhook`.
58+
The `webhooks` argument on these methods still accepts `list[Webhook]` and the fields used at the call site (`event_types`, `request_url`, `payload_template`, `headers_template`) are unchanged. No migration is needed for typical call sites.
7959

8060
## `Actor.new_client` retry and timeout parameters
8161

0 commit comments

Comments
 (0)