Skip to content

Commit 599443b

Browse files
authored
feat(openapi): Add WebhookRepresentation schema for ad-hoc webhooks (#2469)
## Summary - Adds a new `WebhookRepresentation` schema describing the minimal ad-hoc webhook shape (`eventTypes`, `requestUrl`, optional `payloadTemplate` / `headersTemplate`). - References it via `contentSchema` on the `webhooks` query parameter (used on Actor/task run and build endpoints), so the parameter now documents the actual decoded structure of the Base64-encoded JSON array instead of a vague free-form description. ## Why The `webhooks` query parameter is hand-maintained in [`apify-client-python`](https://github.com/apify/apify-client-python) because the spec didn't expose its decoded shape. Lifting it into the spec lets the client generate the model from codegen (apify/apify-client-python#758) and keeps the API reference accurate for any other consumer. ## Related - Pairs with the apify-client-python PR that drops the hand-written `WebhookRepresentation` model in favor of the generated one.
1 parent c32a22b commit 599443b

2 files changed

Lines changed: 36 additions & 2 deletions

File tree

apify-api/openapi/components/parameters/runAndBuildParameters.yaml

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -179,13 +179,19 @@ webhooks:
179179
in: query
180180
description: |
181181
Specifies optional webhooks associated with the Actor run, which can be used to receive a notification
182-
e.g. when the Actor finished or failed. The value is a Base64-encoded
183-
JSON array of objects defining the webhooks. For more information, see
182+
e.g. when the Actor finished or failed. The value is a Base64-encoded JSON array whose items follow
183+
the WebhookRepresentation schema. For more information, see
184184
[Webhooks documentation](https://docs.apify.com/platform/integrations/webhooks).
185185
style: form
186186
explode: true
187187
schema:
188188
type: string
189+
contentEncoding: base64
190+
contentMediaType: application/json
191+
contentSchema:
192+
type: array
193+
items:
194+
$ref: ../schemas/webhooks/WebhookRepresentation.yaml
189195
example: dGhpcyBpcyBqdXN0IGV4YW1wbGUK...
190196

191197
waitForFinishRun:
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
title: WebhookRepresentation
2+
description: |
3+
Minimal representation of an ad-hoc webhook attached to a single Actor run or build via the
4+
`webhooks` query parameter. The query parameter value is a Base64-encoded JSON array whose
5+
items match this schema. Persistent webhook fields (e.g. `condition`) are not used here.
6+
required:
7+
- eventTypes
8+
- requestUrl
9+
type: object
10+
properties:
11+
eventTypes:
12+
type: array
13+
items:
14+
$ref: ./WebhookEventType.yaml
15+
examples:
16+
- [ACTOR.RUN.SUCCEEDED]
17+
requestUrl:
18+
type: string
19+
description: The URL to which the webhook sends its payload.
20+
examples: ["http://example.com/"]
21+
payloadTemplate:
22+
type: [string, "null"]
23+
description: Optional template for the JSON payload sent by the webhook.
24+
examples: ['{\n "userId": {{userId}}...']
25+
headersTemplate:
26+
type: [string, "null"]
27+
description: Optional template for the HTTP headers sent by the webhook.
28+
examples: ['{\n "Authorization": "Bearer ..."}']

0 commit comments

Comments
 (0)