Async renders & webhooks

Heavy renders (long full-page captures, video, slow sites) are better queued than waited on. Instead of holding the connection open, you can queue the render and have Urlbox notify you when it's done.

Queue a render

urlbox render https://example.com --async --webhook-url https://hooks.example/cb

--async queues the render and returns a renderId straight away. When the render finishes, Urlbox sends the result to your --webhook-url. See the webhooks guide for the payload shape and how to verify it.

Check on a render

If you'd rather check the status yourself than run a webhook endpoint, use the renderId:

urlbox status ps_abc123          # the current state, right now
urlbox status ps_abc123 --wait   # wait until it finishes

With --wait, the CLI polls until the render succeeds or fails (or a --timeout you set elapses), then reports the outcome.

When to go async

• The render routinely takes more than a few seconds (large full-page, video).
• You're rendering a long list of URLs and don't want to wait on each in turn.

A render that exceeds its --timeout fails rather than retrying; heavy renders are slow on every attempt, so retrying rarely helps. For genuinely long renders, queue them with --async instead of raising the timeout.