Send an asynchronous render request to Urlbox with a webhook_url. Urlbox will POST to that endpoint when rendering succeeds or fails. In your application, verify the callback’s X-Urlbox-Signature, use renderId to find the queued job, and handle both outcomes. The initial render response only acknowledges job creation; it is not the completed screenshot.
How the webhook workflow works
- Your server sends an authenticated asynchronous render request to
https://api.urlbox.com/v1/render, including the target URL and a publicly reachablewebhook_url. - Urlbox returns a job-creation response. Save its
renderIdand associate it with your internal job or record. - When rendering completes or errors, Urlbox sends a POST callback to your webhook endpoint.
- Verify the signature before trusting the callback, then update the job using its
renderId.
Urlbox documents 201 for creation through /v1/render/async. Common creation errors include 400 for invalid input, 401 for an incorrect key, and 429 for rate limiting. Treat the create response and callback as separate stages.
As an Amazon Associate I earn from qualifying purchases.
Queue a render with a callback URL
Use a server-side request so the Urlbox secret is not exposed to a browser or client application. This example follows the documented POST endpoint and bearer authentication; replace the target and callback URLs and load the secret from your server’s secret store.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →curl -X POST "https://api.urlbox.com/v1/render"
-H "Authorization: Bearer $URLBOX_SECRET"
-H "Content-Type: application/json"
-d '{
"url": "https://example.com",
"webhook_url": "https://your-app.example.com/webhooks/urlbox"
}'Persist the returned renderId alongside your application’s job identifier. Your callback handler can then locate the right record even when multiple renders are in progress.
#1 Best Overall
Handle success and failure callbacks
Implement both documented event types rather than treating every callback as a successful image. The success sample uses render.succeeded and includes a renderId, a result object, and timing metadata. The sample result contains renderUrl, size, renderTime, queueTime, and bandwidth. The failure sample uses render.failed and includes error.message and timing metadata.
These are documented sample payloads, not a guarantee that every listed field appears in every callback. Validate required fields defensively against the current schema. On success, record the render URL or retrieve the image according to your storage plan; on failure, store the error and mark the job failed. Make callback processing idempotent so a repeated delivery cannot create duplicate work or overwrite a terminal state incorrectly.
Verify the Urlbox webhook signature
Urlbox documents the X-Urlbox-Signature header in the form t={timestamp},sha256={token}. Parse the timestamp and token, then calculate an HMAC-SHA256 digest using the webhook secret configured in the project dashboard. The signed input is the timestamp, a period, and the JSON-stringified payload: {timestamp}.{JSON stringified webhook payload}. Compare the calculated digest with the received token using a constant-time comparison.
Free tools Windows power users keep installed
One-click scans. No signup required.
- Use the project webhook secret, not the public callback URL.
- Keep the secret server-side and out of logs, source control, and client-side code.
- Follow Urlbox’s documented serialization procedure. Parsing JSON and serializing it again can alter the representation and cause verification to fail.
- Reject callbacks with a missing, malformed, or invalid signature before changing job state.
Consult Urlbox’s webhook documentation for its current verification examples and contract.
Rank #3
Choose webhooks or polling
Webhooks are useful when renders may take more than a few seconds, when capturing large full pages or slow sites, and when submitting a list of URLs without waiting for each result. If you do not want to expose a callback endpoint, Urlbox’s CLI guide documents polling a render by its renderId as an alternative. For jobs that exceed the configured timeout, the render fails rather than retrying; the CLI guidance says retries rarely help with genuinely long renders, so queue those jobs asynchronously instead.
Choose screenshot options before queuing
The request options shape the render the callback will report. For a full-page capture, Urlbox documents full_page: true; stitch is the default mode, while native is faster but may work less well on some sites. A CSS selector can target a single element instead of the whole page.
For unusually large captures, consider output limits: Urlbox’s screenshot guide states maximum dimensions of 65,535 × 65,535 pixels for JPEG and 16,383 × 16,383 pixels for WebP, and recommends PNG when full-page dimensions make those limits relevant. Choose the mode and format based on page behavior, accuracy, speed, and output-size constraints rather than assuming one option is best for every site.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsRetain the result beyond Urlbox hosting
Urlbox’s Quick Start says a render URL hosted by Urlbox expires after 30 days. A webhook tells your application when the render is ready; it does not, by itself, change how long the hosted file remains available. For longer retention, configure storage in your own infrastructure. Urlbox’s storage guide describes options including use_s3 and s3_path, with additional guides for S3-compatible and other providers.
Troubleshoot common webhook problems
- No callback arrives: confirm that
webhook_urlis included in the render request and that the endpoint is reachable by Urlbox. Check your server’s inbound request logs and callback response behavior. - Creation request is rejected: inspect the response. A
400indicates invalid input,401an incorrect key, and429a rate limit; correct the request, credential, or submission rate as appropriate. - Signature verification fails: confirm you are using the project webhook secret and the exact documented signed input. Do not verify against a parsed-and-reserialized payload if that changes its JSON representation.
- The wrong application job is updated: match the callback’s
renderIdto the saved identifier from the creation response, not to arrival order. - A render fails after taking too long: queue slow or large jobs asynchronously rather than relying on retries for work that exceeds the timeout.
- A saved render URL no longer works: the Quick Start states that Urlbox-hosted renders expire after 30 days. Configure bucket storage for retention beyond that period.
Or skip the browser setup
If you do not specifically need Urlbox’s callback workflow, ScreenshotNeo offers a one-request screenshot API and an MCP server for AI agents. Its clean-shot workflow accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. AI agents can use the MCP tools take_screenshot, get_page_info, and capture_pdf.
Example cURL request (see the ScreenshotNeo API documentation):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpScreenshotNeo’s Free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots. Sign up for ScreenshotNeo’s free plan.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
