Webhooks

The Rendering API can run webhook callbacks after a successful render. These are used internally for uploading the result, updating request logs, and incrementing credits. This section describes the behavior for API consumers.

When webhooks run

For GET /api/render/:pageId and POST /api/render:

1. The render completes and returns the image to the client.
2. The server then runs the configured webhook callback (e.g. upload buffer to storage, update log entry, increment space credits).

Callbacks are fire-and-forget from the client's perspective: the response is the image (or error). Failures in the callback do not change the HTTP status of the render response.

What the callback receives

The callback is invoked server-side with:

• The request event (so it can read headers, token, request ID).
• The handler result (e.g. the image buffer).

It can then:

• Upload the image to your storage (e.g. R2, S3) and attach the file to the log for that request (via requestId).
• Increment credits for the space associated with the API token.

So each render can be logged and billed even though the client only receives the image.

Logs and request ID

When request logging is enabled, each render request gets a request ID. The webhook can use this to find the log document and update it with the rendered file (e.g. URL or file reference). That lets you see in Settings → Space → Logs which request produced which asset.

Configuring webhooks

Webhook behavior is configured in the server (e.g. in the render action's webhook.callback). There is no per-request webhook URL from the client: the client only sends the render request with a valid API token; the server runs the configured callback after the render.

If you need outbound webhooks (e.g. HTTP POST to your URL when a render finishes), that would be a separate feature (e.g. a configurable webhook URL per space). The current implementation uses internal callbacks for upload, logging, and credits.

Summary