Website Screenshot API with Webhook Notification When Capture Is Ready
Submit a screenshot job, receive a webhook when it finishes, and build a secure, idempotent callback flow with provider-specific behavior in mind.
To get notified when a website screenshot is ready, submit an asynchronous capture request with the target URL, rendering options, and a callback URL. The API should acknowledge the queued job and return an identifier; after rendering, it sends an HTTP POST to your callback endpoint. Your endpoint should verify the sender when signatures are supported, persist the event, acknowledge it with the documented success status, and process the image idempotently.
Webhook support, request parameters, event payloads, retries, and result retention vary by provider and deployment. Check the current documentation for the exact service and plan before relying on callbacks in production. A 202 response means the job was accepted for processing, not that the screenshot is ready. Apple’s webhook documentation describes the general pattern as event-driven delivery to a predefined callback URL.
How the asynchronous screenshot workflow works
- Submit a job. Send the page URL, any rendering options, and the provider’s callback parameter (often named something like
webhook_url). Parameter names differ. - Store the acknowledgement. Record the provider job ID and initial status. An HTTP 202 or equivalent is an acceptance acknowledgement, not a completed image.
- Receive the callback. The provider POSTs an event to your public HTTPS endpoint when rendering completes or, if supported, fails. Payloads may include a status, job ID, image URL or data, MIME type, timing, and error details.
- Validate and persist. Verify the callback signature according to the provider’s instructions, then save the event and state durably before acknowledging it.
- Process the result. Download or handle the image in a worker. Make processing safe to repeat in case the provider sends a duplicate event.
There is no universal payload schema, delivery guarantee, retry policy, or retention period. Confirm each with the provider rather than assuming behavior based on another API.
Choose an API that really supports callbacks
First check that asynchronous capture and callbacks are currently enabled for the specific deployment and plan you intend to use. Provider documentation can describe features that are disabled on a particular deployment. For example, ScreenshotMAX documents async requests with an optional callback, while the cited screenshotapis.org guide says callbacks are unavailable on its deployment and requests return 503 without charging a credit. ScreenshotRun also describes callback-based completion and failure events. These are provider-specific details; recheck the live documentation before integrating.
| What to verify | Why it matters |
|---|---|
| Async and webhook availability | Feature availability may differ by deployment or plan. |
| Job identity | Know how the initial acknowledgement and callback correlate to the same capture. |
| Completion and failure events | Determine whether every terminal outcome triggers a callback and what status values mean. |
| Signature verification | Check signing method, secret configuration, header names, and whether verification requires the raw request body. |
| Acknowledgement and retries | Find the required success status and documented retry/backoff behavior. If unspecified, ask the provider. |
| Result delivery and retention | Establish whether the result is a URL, bytes, or metadata, and how long it remains available. |
| Limits and cost | Compare quotas, render options, workload volume, and billing rules with your expected use. |
Build a reliable webhook receiver
1. Make the callback endpoint reachable
Use a publicly reachable HTTPS URL that accepts the HTTP method and content type specified by the screenshot provider. A local development server is not reachable from the provider without a secure tunnel or a deployed test endpoint. Keep callback secrets out of URLs and source control.
2. Verify before trusting the event
If the provider signs callbacks, follow its verification recipe exactly. Some HMAC schemes require the unmodified raw request bytes; parsing and reserializing JSON first changes the signed content. Compare signatures safely using the framework’s constant-time comparison function. Do not invent a signature header, canonicalization rule, or HMAC input: use the provider’s documented format.
3. Persist before acknowledging
After signature verification, write the provider event ID (if supplied), job ID, event type or status, and receipt time to durable storage. Return the provider’s documented 2xx response only after the event is safely recorded. Acknowledge quickly; move image downloading, resizing, or other slow work into a background queue.
4. Make handling idempotent
Use a unique event ID when the provider supplies one. Otherwise, define a deduplication key from documented stable fields, such as provider job ID plus terminal status, and enforce uniqueness in storage. A repeated callback should not create duplicate user-visible work or charge your own downstream systems twice. Preserve state transitions so a late or duplicate event cannot incorrectly replace a terminal result.
5. Retrieve and protect the screenshot
Use the provider’s documented result field and retention window. If the callback includes a temporary result URL, download it promptly and store it in your own controlled storage if it must persist longer. Treat callback payloads and result URLs as untrusted input: validate schemes and hosts as appropriate, enforce size limits, and avoid exposing private captures through public logs or error pages.
Example request and callback contract
Every service defines its own request and payload. The following is an illustrative shape only; replace the endpoint, parameter names, authentication, response fields, and signature verification with the selected provider’s current API contract.
POST /capture
Content-Type: application/json
{
"url": "https://example.com/report",
"webhook_url": "https://app.example.com/hooks/screenshot"
}HTTP/1.1 202 Accepted
Content-Type: application/json
{
"job_id": "provider-job-id",
"status": "queued"
}POST /hooks/screenshot
Content-Type: application/json
{
"job_id": "provider-job-id",
"status": "completed",
"result_url": "https://provider.example/result/temporary-id"
}Do not deploy the illustrative payload as if it were a shared standard. Confirm whether the provider sends a failure callback, how it identifies the job, and how it expects the receiver to respond.
Operational checklist
- Callback URL uses HTTPS and is reachable from the provider’s network.
- Webhook support is enabled for the selected service, deployment, and plan.
- Signature verification matches the documented algorithm and raw-body requirements.
- Job IDs and callback events are persisted with enough information to investigate failures.
- The endpoint acknowledges only after durable recording and responds with the documented status.
- Duplicate events are safe, and terminal state transitions are guarded.
- Slow result retrieval and image processing happen outside the request handler.
- Retry behavior, result retention, quotas, and cost have been confirmed with current provider docs.
- Logs omit secrets and avoid recording sensitive screenshot contents or signed URLs.
Performance, reliability, and cost
Callbacks are useful when rendering might outlast a reasonable synchronous request or when an application has many captures to coordinate. This is an architectural reason to use the pattern, not a promise of a particular render time. The initial response lets the caller release its connection and continue other work while the provider renders.
Reliability depends on both the provider’s delivery behavior and your receiver. A durable queue or database, fast acknowledgement, idempotent processing, and operational visibility help prevent transient application failures from losing work. Confirm whether the provider retries, for how long, and which response codes trigger another attempt; the cited provider sources do not establish one shared policy. Consider a reconciliation path for jobs that remain pending beyond your own threshold, using whatever status lookup the provider documents.
Cost depends on the provider’s pricing model, options, quotas, and whether failed jobs or retries count. Do not infer a universal charge rule. Estimate volume from expected captures and verify how full-page rendering, higher-resolution output, retries, and retained results affect your bill.
Troubleshooting
| Symptom | Likely cause | What to check or fix |
|---|---|---|
| No callback arrives | Callback feature is unavailable or disabled; URL is unreachable; job is still rendering; provider only sends selected event types. | Check current deployment and plan support, provider job status, endpoint access logs, firewall rules, TLS certificate, and callback event configuration. |
| Provider reports callback failure | Receiver returned a non-2xx status, timed out, or was unreachable. | Return the documented success status after durable persistence. Keep the handler short and inspect provider delivery logs. |
| Signature validation fails | Wrong secret, wrong header or algorithm, parsed body used instead of raw bytes, or an incorrect timestamp tolerance. | Use the exact provider instructions and raw request body where required. Check secret rotation and compare signatures in constant time. |
| Same job is processed more than once | Duplicate delivery or provider retry after an acknowledgement was lost. | Add a unique constraint or idempotency record and make downstream actions repeat-safe. |
| Callback arrives but image download fails | Temporary result URL expired, access credentials are missing, or the callback indicates failure rather than completion. | Inspect status and error fields, fetch promptly, and follow the provider’s documented authentication and retention behavior. |
| Initial request seems successful but no image is ready | The acknowledgement only means the asynchronous job was accepted. | Store the job ID and wait for its completion event or use the documented status mechanism. |
| Callback endpoint works locally but not in production | Provider cannot reach a private address, local hostname, or blocked route. | Use a public HTTPS endpoint and verify network allowlists, DNS, and TLS from outside your environment. |
| Callback endpoint returns 503 | The provider’s current deployment may not have callback support. | Check its live documentation and status; do not assume a generic API guide applies to the deployment you are calling. |
Or skip the browser setup
For a direct screenshot without building a browser-rendering service, ScreenshotNeo offers a one-call screenshot API. The API request below is synchronous, so it returns the image response rather than notifying your application later through a webhook. See the ScreenshotNeo API documentation for request options and response behavior.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for 1,000 free screenshots a month, with no card required.
FAQ
Does HTTP 202 mean the screenshot is finished?
No. It generally indicates acceptance of an asynchronous job. Use the callback or the provider’s documented status mechanism to learn when it completes.
Should the webhook handler download the screenshot before responding?
Usually keep the handler fast: verify and persist the event, acknowledge it, and let a worker retrieve the result. Follow the provider’s contract and make sure a temporary result URL will remain valid long enough for that worker.
Can I assume every screenshot API retries failed callbacks?
No. Retry rules are provider-specific and may be undocumented. Verify the policy and build duplicate-safe handling regardless.
Is ScreenshotNeo a webhook screenshot API?
The ScreenshotNeo call shown here returns a screenshot directly in one GET request. Its documented facts for this article do not establish a webhook completion flow, so use it for direct capture rather than assuming it will POST a callback.
