Save Screenshots to S3 with Webhooks and Retries | ScreenshotCenter

Why deliver screenshots to S3?

Most teams that capture screenshots at scale need them in a central storage bucket — for compliance archives, ML pipelines, client portals, or integration with downstream tools. Downloading each image individually doesn't scale.

ScreenshotCenter's S3 app integration pushes completed screenshots directly to your bucket. Combine it with webhooks for real-time notifications, and you have a fully automated pipeline with zero download code.

Architecture overview

1. Your code submits a screenshot request with the apps parameter pointing to your S3 integration.
2. ScreenshotCenter renders the page in a real browser.
3. The finished image is uploaded to your S3 bucket using the path template you configured.
4. A webhook fires to your endpoint with the screenshot ID, status, and S3 path.

Setting up the S3 integration

1. In the ScreenshotCenter dashboard, go to Apps → S3 and create a new integration.
2. Enter your bucket name, region, access key ID, and secret access key.
3. Define a path template using tokens: screenshots/{domain}/{yyyy}/{mm}/{dd}/{id}.png
4. Click Test to verify credentials. The integration uploads a test file and confirms it worked.

Request example

curl -X POST https://api.screenshotcenter.com/v1/screenshot \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.example.com",
    "format": "png",
    "size": "page",
    "apps": {
      "my-s3-integration": "archive/{domain}/{id}.png"
    }
  }'

The apps object maps your integration ID to the path template for this specific request. You can override the default template per request if needed.

Webhook handling

Configure a webhook URL in your dashboard. When a screenshot finishes (or fails), ScreenshotCenter sends a POST with:

{
  "event": "screenshot.finished",
  "screenshot_id": "abc123",
  "status": "finished",
  "image_url": "https://api.screenshotcenter.com/...",
  "apps": {
    "my-s3-integration": {
      "status": "finished",
      "path": "archive/example.com/abc123.png"
    }
  }
}

Check the apps object to confirm the S3 upload succeeded before processing downstream.

Retry logic

• S3 retries: ScreenshotCenter retries failed uploads up to 3 times with exponential backoff.
• Webhook retries: If your endpoint returns a non-2xx status, the webhook is retried up to 5 times.
• Idempotency: Store each screenshot_id before responding 200 to avoid duplicate processing.

Batch delivery

For high-volume workflows, use the batch API to submit hundreds of URLs at once. Each completed screenshot in the batch triggers the S3 upload and webhook independently.

Security best practices

Practice	Why
Use a dedicated IAM user with s3:PutObject only	Minimize blast radius if credentials leak
Block public ACLs on the bucket	Prevent accidental public exposure
Enable bucket versioning	Recover from overwrites or deletions
Rotate access keys quarterly	Standard credential hygiene
Set lifecycle rules	Move old screenshots to Glacier for cost savings

FAQ

Does S3 delivery work with S3-compatible storage (Wasabi, MinIO, R2)?

Yes. The S3 integration supports any S3-compatible endpoint — just enter your custom endpoint URL in the configuration.

Can I use different path templates per request?

Yes. The apps parameter in the request overrides the default template. Useful for routing different types of screenshots to different folder structures.

What happens if the S3 upload fails?

The screenshot is still available for download via the API. Check /screenshot/info for the app-level status and retry from there.

Ready to automate? Set up S3 delivery in under five minutes.