> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenshotmax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Async and Webhooks

> For long-running or high-volume tasks, you can choose to receive the result asynchronously via a webhook.

# 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

| Parameter        | Type   | Description                                                          |
| ---------------- | ------ | -------------------------------------------------------------------- |
| `webhook_url`    | string | The URL to which the webhook will be sent.                           |
| `webhook_signed` | bool   | If true, the webhook payload will be signed using your `secret_key`. |

### Webhook Signature (Optional but recommended)

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.

<Warning>Be sure to use the raw body (as a string) before any parsing.</Warning>

## Webhook Payload

```json theme={null}
{
  "id": "id-of-request",
  "file": "https://cache.screenshotmax.com/<hash>.<ext>",
  "expires": 1722625200,
  "created": 1716898800
}
```

| Field     | Type   | Description                                              |
| --------- | ------ | -------------------------------------------------------- |
| `id`      | string | The unique identifier for the request.                   |
| `file`    | string | The URL to the generated file.                           |
| `expires` | number | The timestamp (in seconds) when the file will expire.    |
| `created` | number | The timestamp (in seconds) when the request was created. |

**Example API Request**

```json theme={null}
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](https://webhook.site) to inspect incoming payloads
* Use [ngrok](https://ngrok.com/) 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](https://app.screenshotmax.com/requests).
* Optionally delivered to your `webhook_url`, if provided.

## How to Use

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

**POST Example**

```json theme={null}
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:

```json theme={null}
{
  "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](mailto:support@screenshotmax.com)