Asynchronous Processing with Webhooks

The Screenshots API supports webhook callbacks for asynchronous screenshot processing. This is particularly useful for:

• Long-running captures (full page, high resolution)
• Bulk screenshot operations
• Integration with your existing systems

How Webhooks Work

1. You make a request to the API with a webhook URL
2. The API immediately acknowledges your request
3. The screenshot is processed in the background
4. When complete, the API calls your webhook URL with the results

Setting Up a Webhook

Here's how to use webhooks in your application:

async function takeScreenshotWithWebhook() {
  const response = await fetch('https://api.screenshotsapi.dev/screenshot', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({
      url: 'https://example.com',
      webhook: 'https://your-webhook-url.com/callback',
      fullPage: true,
      blockAds: true
    })
  });
  
  // The API will return immediately
  const { requestId } = await response.json();
  return requestId;
}
 
// Your webhook endpoint
app.post('/callback', async (req, res) => {
  const { status, url, metadata } = req.body;
  
  if (status === 'success') {
    console.log('Screenshot ready:', url);
    console.log('Metadata:', metadata);
  } else {
    console.error('Screenshot failed:', req.body.error);
  }
  
  res.status(200).send('OK');
});

Webhook Payload

When your webhook is called, you'll receive a JSON payload with the following structure:

{
  "status": "success",
  "url": "https://your-bucket.s3.amazonaws.com/screenshots/example.jpg",
  "metadata": {
    "width": 1920,
    "height": 1080,
    "format": "jpeg",
    "timestamp": "2024-03-20T12:00:00Z"
  }
}

If there's an error, you'll receive:

{
  "status": "error",
  "error": "Error message description",
  "timestamp": "2024-03-20T12:00:00Z"
}

Best Practices

1. Secure Your Webhook: Use HTTPS and validate incoming requests
2. Handle Retries: The API will retry failed webhook calls
3. Process Quickly: Respond to webhooks within 5 seconds
4. Log Everything: Keep records of all webhook events
5. Monitor Status: Track the status of your screenshot requests

Common Use Cases

1. Bulk Processing: Capture multiple screenshots asynchronously
2. High-Resolution Captures: Process large screenshots in the background
3. Integration: Connect with your existing systems and workflows
4. Monitoring: Track the status of your screenshot requests