From 39f4c6434dd3f121153ac3d2da23be54de7e696f Mon Sep 17 00:00:00 2001 From: Ming Lu Date: Fri, 7 Aug 2026 08:22:33 -0700 Subject: [PATCH 1/2] add docs for webhooks --- .../docs/ai-gateway/usage/rest-api.mdx | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/src/content/docs/ai-gateway/usage/rest-api.mdx b/src/content/docs/ai-gateway/usage/rest-api.mdx index 04b799040bd..1988437af66 100644 --- a/src/content/docs/ai-gateway/usage/rest-api.mdx +++ b/src/content/docs/ai-gateway/usage/rest-api.mdx @@ -116,6 +116,61 @@ curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ }' ``` +### Background requests and webhooks + +By default, `/ai/run` requests are synchronous — the connection stays open until the model finishes and the result comes back in the response. For long-running models — such as image, video, or audio generation — or when you do not want to hold a connection open, run the request in the background and have AI Gateway notify a webhook when it completes. + +Set `background` to `true` and provide a `webhookUrl`. Both are fields on the `options` object of the `/ai/run` body, alongside `model` and `input`. + +```bash +# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID, +# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN. +curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run" \ + --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ + --header "Content-Type: application/json" \ + --data '{ + "model": "google/nano-banana", + "input": { + "prompt": "A cozy coffee shop interior with warm lighting, plants hanging from the ceiling, and a cat sleeping on a velvet armchair by the window", + "aspect_ratio": "16:9" + }, + "options": { + "background": true, + "webhookUrl": "https://example.com/my-webhook" + } + }' +``` + +A background request returns immediately while the model runs. The result is delivered to your webhook when the run completes. + +#### Webhook payload + +When the run completes, AI Gateway sends a single `POST` request to your `webhookUrl` with the run outcome: + +```json +{ + "id": "", + "state": "", + "result": {}, + "error": null, + "provider": "google-vertex-ai", + "model": "google/nano-banana", + "usage": {} +} +``` + +Webhook delivery is best-effort and is not retried. The destination must be an HTTPS URL that does not resolve to a private network address. + +#### Webhook format + +Use the optional `webhookFormat` field (also on `options`) to control the shape of the webhook body. The default is `raw`. + +| Format | Description | +| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `raw` | Sends the payload as-is (default). | +| `chat` | Wraps the payload in `{ "text": "" }`, matching the incoming-webhook body accepted by Google Chat and Slack. | +| `replicate` | Sends the raw payload and adds an `X-Webhook-Signature` header (HMAC-SHA256 of the run ID) so you can verify the request's origin. | + ## `/ai/v1/chat/completions` — OpenAI compatible Uses the standard OpenAI chat completions format. The `model` field uses the same `author/model` naming. This endpoint is compatible with the OpenAI SDK and other OpenAI-compatible clients. From 3c2a0d69c88a7ce04f9effced61d4e9430adb41b Mon Sep 17 00:00:00 2001 From: Ming Lu Date: Fri, 7 Aug 2026 08:49:25 -0700 Subject: [PATCH 2/2] Remove replicate webhook format from docs The replicate format signs with an internal worker-level secret that customers cannot configure, so it is not a general-purpose option. --- src/content/docs/ai-gateway/usage/rest-api.mdx | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/content/docs/ai-gateway/usage/rest-api.mdx b/src/content/docs/ai-gateway/usage/rest-api.mdx index 1988437af66..d018c3693fd 100644 --- a/src/content/docs/ai-gateway/usage/rest-api.mdx +++ b/src/content/docs/ai-gateway/usage/rest-api.mdx @@ -165,11 +165,10 @@ Webhook delivery is best-effort and is not retried. The destination must be an H Use the optional `webhookFormat` field (also on `options`) to control the shape of the webhook body. The default is `raw`. -| Format | Description | -| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `raw` | Sends the payload as-is (default). | -| `chat` | Wraps the payload in `{ "text": "" }`, matching the incoming-webhook body accepted by Google Chat and Slack. | -| `replicate` | Sends the raw payload and adds an `X-Webhook-Signature` header (HMAC-SHA256 of the run ID) so you can verify the request's origin. | +| Format | Description | +| ------ | ----------------------------------------------------------------------------------------------------------------------------- | +| `raw` | Sends the payload as-is (default). | +| `chat` | Wraps the payload in `{ "text": "" }`, matching the incoming-webhook body accepted by Google Chat and Slack. | ## `/ai/v1/chat/completions` — OpenAI compatible