​
Sending a Webhook

​
How It Works

Instead of waiting for the result in the API response, you can provide a webhook_url in your request. Once the rendering is complete, we will send a POST request to that URL with the result.

Your webhook_url must:

  • Be publicly accessible over HTTPS or HTTP
  • Accept POST requests
  • Return a 2xx HTTP status code to acknowledge the event

​
Request Parameters

ParameterTypeDescription
webhook_urlstringThe URL to which the webhook will be sent.
webhook_signedboolIf true, the webhook payload will be signed using your secret_key.

If webhook_signed is set to true, we include a signature in the webhook request header:

X-Screenshotmax-WebHook-Signature: <sha256_hmac_signature>

This signature is generated using the HMAC SHA256 algorithm with your secret_key and the payload. You can verify the signature to ensure the request is from us.

​
How to Verify the Signature

To verify the signature on your server:

  1. Serialize the exact raw JSON body of the request.
  2. Compute the HMAC SHA-256 hash using your secret_key.
  3. Compare your computed hash with the value in the X-Screenshotmax-WebHook-Signature header.
Be sure to use the raw body (as a string) before any parsing.

​
Webhook Payload

{
  "id": "id-of-request",
  "file": "https://cache.screenshotmax.com/<hash>.<ext>",
  "expires": 1722625200,
  "created": 1716898800
}
FieldTypeDescription
idstringThe unique identifier for the request.
filestringThe URL to the generated file.
expiresnumberThe timestamp (in seconds) when the file will expire.
creatednumberThe timestamp (in seconds) when the request was created.

Example API Request

POST https://api.screenshotmax.com/v1/screenshot
{
  "url": "https://example.com",
  "access_key": "YOUR_ACCESS_KEY",
  "webhook_url": "https://yourserver.com/webhook-handler",
  "webhook_signed": true
}

​
Tips for Testing

  • Use Webhook.site to inspect incoming payloads
  • Use ngrok to expose local endpoints for testing

​
Async Request

If you don’t want to wait for the rendering result immediately in the response, you can process the request in asynchronous mode by setting the async parameter to true.

​
What Happens in Async Mode?

When you set async to true in your request:

  • The API immediately responds with a 202 Accepted.
  • The rendering job is queued and processed in the background.

Once complete, the result is:

  • Visible in your dashboard under the Requests section.
  • Optionally delivered to your webhook_url, if provided.

​
How to Use

Add the async parameter to your request (either GET or POST):

POST Example

POST https://api.screenshotmax.com/v1/screenshot
{
  "url": "https://example.com",
  "access_key": "YOUR_ACCESS_KEY",
  "async": true
}

GET Example

GET https://api.screenshotmax.com/v1/screenshot?url=https://example.com&access_key=YOUR_ACCESS_KEY&async=true

​
API Response

When you set async to true, the API will respond with a 202 Accepted status code. The response will look like this:

{
  "status": "Accepted",
  "message": "The request has been accepted for processing",
  "created": 1744030537
}

​
Tracking the Result

After submission, the job will appear in your Requests dashboard. You can:

  • View status (done, failed)
  • Download the result once complete

If you included a webhook_url, you will also receive the result automatically once ready

Need help? Contact us at support@screenshotmax.com