ScreenshotOne Webhook Not Firing: Troubleshooting Delivery Failures

If a ScreenshotOne webhook is not firing, identify which stage failed: request configuration, screenshot execution, callback delivery, receiver acceptance, or downstream processing. Start by checking the exact API request and its response, then search the receiving endpoint’s logs for the POST. Enable webhook_errors=true when failed screenshot executions should also reach the callback. ScreenshotOne’s reviewed documentation does not specify callback retry behavior, so do not assume a failed delivery will be retried.

1. Confirm the webhook request is configured

webhook_url is the callback destination. ScreenshotOne sends execution results to it in a POST body. Webhooks work with synchronous and asynchronous requests, although they are commonly paired with async=true; asynchronous mode is false by default. Verify the URL in the actual request, including encoding, path, scheme, and any required query parameters. The receiver must be publicly reachable and accept POST.

For JSON callback content, request response_type=json. ScreenshotOne’s documented example returns a screenshot_url; when storage is used, storage_return_location=true can return a storage location. Without JSON response mode, the result may be binary screenshot data. A receiver that always parses JSON can therefore reject or mishandle the body.

curl -G 'https://api.screenshotone.com/take' \\
  --data-urlencode 'access_key=YOUR_API_KEY' \\
  --data-urlencode 'url=https://example.com' \\
  --data-urlencode 'webhook_url=https://app.example.com/hooks/screenshotone' \\
  --data-urlencode 'async=true' \\
  --data-urlencode 'response_type=json' \\
  --data-urlencode 'webhook_errors=true'

Keep the API key out of source control and logs. The endpoint and option behavior described here comes from ScreenshotOne’s [Async and Webhooks documentation](https://screenshotone.com/docs/async-and-webhooks/) and [options reference](https://screenshotone.com/docs/options/).

2. Establish whether screenshot execution succeeded

A callback can appear absent because there was no successful execution result to deliver. By default, errors are not sent to webhook_url. Set webhook_errors=true to include error information; with JSON it is in the body, and error details are also available in headers. Inspect error_code, error_message, and documentation_url when present.

Read the original API response and classify it before changing callback code. ScreenshotOne API errors include a code, human-readable message, and HTTP status. Its error handling guide generally treats 400–499 as request-side errors and 500–599 as API-side errors, but calls out exceptions, including target network_error and a 4xx host_returned_error. Follow the specific error guidance instead of retrying every failure identically. See the [error handling guide](https://screenshotone.com/docs/errors-handling/) and [error reference](https://screenshotone.com/docs/errors/).

Rendering timeouts are an upstream execution problem, not proof of webhook transport failure. ScreenshotOne documents adjusting timeout or navigation_timeout, reducing an excessive delay, changing wait_until, or using async/webhooks for longer operations. Consult the [timeout guide](https://screenshotone.com/docs/handle-timeout/).

3. Check the receiving endpoint and downstream handling

Search reverse-proxy, hosting-platform, and application logs around the request time. Check the callback URL, POST method, timestamp, response status, and request identifiers. Then place the failure in one of these cases:

Evidence	Likely stage	What to check
No inbound POST in receiver logs	Configuration or transport	Exact URL, DNS, TLS certificate, firewall, public reachability, route, and whether ScreenshotOne produced a result.
POST arrived; endpoint returned an error	Receiver acceptance	Route and method, authentication middleware, signature validation, payload limits, rate limits, and runtime timeout.
Endpoint returned success; application has no event	Downstream processing	Body parsing, schema validation, queue publication, transaction rollback, and worker failures.
POST arrived but JSON parsing failed	Payload handling	Confirm response_type=json; otherwise the result may be binary rather than JSON.

These receiver-side checks follow from the documented POST callback pattern; exact routing, logging, and processing behavior depends on your endpoint implementation. Record whether your handler returned a success status and whether it durably accepted the event. A response from the endpoint does not by itself prove a downstream job completed.

4. Validate the webhook signature against the raw body

Webhook requests include X-ScreenshotOne-Signature. Validate the body with HMAC SHA-256 using the webhook secret from the access page. The webhook secret is different from the API key. Header names are case-insensitive in HTTP, so code should not depend on one capitalization.

Signature verification commonly fails when code uses the API key instead of the webhook secret, computes the signature over parsed and re-serialized JSON rather than the exact raw request bytes, or uses an outdated secret. Preserve the raw body before JSON parsing and compare signatures with a constant-time comparison. The exact encoding and signature construction should follow ScreenshotOne’s current [webhook documentation](https://screenshotone.com/docs/async-and-webhooks/); do not guess a format if verification fails.

5. Correlate the API request and callback

Use ScreenshotOne’s debugging headers to connect evidence across your API client, callback receiver, and support request. The x-screenshotone-trace-id is a unique request trace ID. x-screenshotone-reference is a screenshot or video ID that may appear in history or be useful to support. x-screenshotone-external-identifier is a value you supply to track success or errors.

These headers are for debugging and support; do not use trace or reference IDs as application logic. Keep a record of the external identifier with your own job record. See the [debug headers reference](https://screenshotone.com/docs/debug-headers/).

6. Troubleshooting checklist

1. Capture the exact outgoing request options with credentials redacted. Confirm webhook_url and, if expected, async=true.
2. Confirm the callback URL is externally reachable and accepts POST at the specified route.
3. Check the original API response, status, error code, and response headers to see whether screenshot execution produced a result.
4. Set webhook_errors=true if execution failures should be sent to the callback, and inspect error fields.
5. Search receiver and proxy logs for the inbound POST and record the HTTP status your handler returned.
6. Verify the signature using the webhook secret and raw body; never substitute the API key.
7. If the receiver accepted the event, follow it into queues, transactions, and workers.
8. Correlate logs with trace/reference IDs and an external identifier; redact all secrets.

7. Common errors and fixes

Symptom	Cause to investigate	Fix
No callback and no receiver log	Missing or malformed webhook_url, private development URL, DNS/TLS/firewall issue, or no execution result.	Verify the sent URL and public reachability; inspect the original API response and enable webhook_errors.
Callback appears only for successful captures	webhook_errors is false, its default.	Set webhook_errors=true when errors should be reported.
Signature mismatch	Wrong secret, API key used as secret, or body transformed before HMAC calculation.	Use the webhook secret and exact raw body; follow the documented signature format.
JSON decoder error	Receiver assumes JSON while response mode is binary.	Set response_type=json when the handler expects JSON, or handle binary results correctly.
Callback returns 404 or 405	Wrong route or method not enabled.	Point to the exact route and accept POST.
Callback returns 401 or 403	Receiver authentication or signature middleware rejects the request.	Inspect middleware logs and validate with the separate webhook secret.
Callback returns 413, 429, or 5xx	Receiver payload limit, rate limit, or server/runtime failure.	Inspect proxy and application limits, capacity, and timeouts; return success only after the event is safely accepted.
Timeout-related API error	Rendering or navigation exceeded its configured wait.	Use the timeout guidance: adjust timeout settings, reduce delay, or revisit wait_until.
Endpoint returns success but no completed work	Event was acknowledged before durable processing, or a queue/worker/transaction failed.	Trace the event through persistence and downstream workers; log the external identifier.

8. Reliability, retries, and cost considerations

The reviewed official docs do not specify webhook delivery retries or an account delivery-attempt history. Do not rely on an undocumented retry schedule. Design the receiver to log each accepted event, make processing safe to repeat where appropriate, and expose failures in your own monitoring. If the API request itself returned an internal error, ScreenshotOne’s internal error article advises replaying the request and contacting support if the issue repeats; that advice concerns API request errors, not a guarantee of webhook redelivery. See [internal error guidance](https://screenshotone.com/docs/internal-error/).

Keep execution errors separate from delivery errors in metrics. Track API status/error code, callback receipt and response status, signature outcome, processing outcome, and elapsed time. Do not blindly repeat non-retryable request errors. For a suspected service-side or delivery issue, retain UTC timestamps and correlation IDs so support can investigate without exposing credentials.

9. Contact support with useful evidence

If the issue persists, contact ScreenshotOne support with the UTC timestamp, trace ID, reference ID if available, external identifier, sanitized request options, API status/error code, receiver status, and relevant sanitized logs. Never send the API key or webhook secret. The [debug headers documentation](https://screenshotone.com/docs/debug-headers/) describes the identifiers.

10. FAQ

Does ScreenshotOne automatically retry failed webhook POSTs?

The reviewed official documentation does not specify callback retry behavior. Do not assume retries; confirm with support if delivery retry policy is essential to your integration.

Is the webhook secret the same as the API key?

No. Use the webhook secret from the access page to validate the callback signature.

Will failed screenshot executions reach my webhook?

Not by default. Set webhook_errors=true to receive error details.

Can I use a webhook with a synchronous request?

Yes. The documentation says webhooks can be used with synchronous and asynchronous requests, while async mode is commonly used and defaults to false.

Or skip the browser setup

If your goal is to receive a screenshot rather than operate a browser capture stack, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. For example:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation. Cookie banners, popups, and chat widgets are removed before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

Sign up free for 1,000 screenshots a month, no card required.