Webhooks

Webhooks allow your application to receive information when a screenshot has been rendered. This allows you to render screenshots asynchronously.

Pass your webhook URL in as an option and Urlbox will send a POST request back to that URL with data about the screenshot in JSON format once it has completed rendering.

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com", "webhook_url":"https://example.com/webhooks/urlbox"}'

This will result in a response like the following being posted to https://example.com/webhooks/urlbox once the render is complete:

{
    "event": "render.succeeded",
    "renderId": "19a59ab6-a5aa-4cde-86cb-d2b23302fd84",
    "result": {
        "renderUrl": "https://renders.urlbox.io/urlbox1/renders/6215a3df94d7588f7d910513/2022/7/6/19a59ab6-a5aa-4cde-86cb-d2b23302fd84.png",
        "size": 34097
    },
    "meta": {
        "startTime": "2022-07-06T17:49:18.593Z",
        "endTime": "2022-07-06T17:49:21.103Z"
    }
}

Webhooks are often used in combination with our S3 storage options making it easy for you to gather large numbers of screenshots asynchronously.

You can verify Urlbox as the source of a webook using the value of the x-urlbox-signature header. Please contact support for your unique webhook secret. You will then be able to validate the signatures in the webhooks you receive.