Skip to main content
Instead of polling the API for screenshot status, you can provide a webhookUrl to receive a notification when the screenshot is ready.

​
How it works

  1. You send a capture request with a webhookUrl parameter
  2. The API returns a 202 Accepted response immediately with the screenshot ID
  3. When the screenshot is complete (or fails), Screenshotly sends a POST request to your webhook URL

​
Sending a request with a webhook

const screenshot = await client.capture({
  url: 'https://example.com',
  webhookUrl: 'https://your-server.com/webhook/screenshots'
});

// Returns immediately with the screenshot ID
console.log('Job ID:', screenshot.data.id);

​
Webhook payload

When the screenshot is ready, Screenshotly sends a POST request to your webhook URL with a JSON body: 
{
  "id": "scr_abc123",
  "status": "completed",
  "url": "https://example.com",
  "screenshotUrl": "https://api.screenshotly.dev/api/v1/screenshots/scr_abc123.png",
  "format": "png",
  "requestedAt": "2025-05-14T10:00:00Z",
  "completedAt": "2025-05-14T10:00:03Z"
}
If the capture fails: 
{
  "id": "scr_abc123",
  "status": "failed",
  "url": "https://example.com",
  "error": "Page load timeout exceeded",
  "requestedAt": "2025-05-14T10:00:00Z"
}

​
Handling webhooks

Here’s an example Express.js handler for receiving webhook notifications: 
app.post('/webhook/screenshots', (req, res) => {
  const { id, status, screenshotUrl, error } = req.body;

  if (status === 'completed') {
    console.log(`Screenshot ${id} ready at: ${screenshotUrl}`);
    // Save the URL, notify users, process the image, etc.
  } else if (status === 'failed') {
    console.error(`Screenshot ${id} failed: ${error}`);
    // Handle the failure, retry, or alert
  }

  // Respond with 200 to acknowledge receipt
  res.status(200).send('OK');
});
Your webhook endpoint must respond with a 2xx status code within 10 seconds. If the endpoint fails or times out, Screenshotly may retry the notification.

​
Best practices

  • Verify requests — validate incoming webhook requests to ensure they originate from Screenshotly
  • Respond quickly — return a 200 response immediately, then process the payload asynchronously
  • Handle duplicates — your endpoint may receive the same notification more than once; use the screenshot id for deduplication
  • Use HTTPS — always use an HTTPS endpoint for your webhook URL

​
Plan availability

Webhook notifications are available on the Pro plan and above.