webhooks.mdx

id	title	description
webhooks	Webhooks	Get notified when a screenshot has been rendered.

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

Pass a webhook URL in as the webhook_url 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"
  }
}

~> Urlbox also accepts HEAD requests, in case you just want to get the response status/headers without pulling down the full response body.

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. You can find your webhook secret from within the project settings in your Urlbox dashboard. You will then be able to validate the signatures in the webhooks you receive.