Workflow Integration

Webhooks

Receive real-time HTTP POST events to your own endpoint when screenshot or batch jobs finish. Webhooks are the most flexible integration — build exactly the automation you need with no third-party platforms required.

Events

screenshot.finished

Single screenshot job completed. Includes image URL, dimensions, and metadata.

screenshot.failed

Screenshot job failed after all retries. Includes the error reason.

batch.finished

All jobs in a batch completed. Includes per-job status summary.

app.upload.finished

A storage app (Drive, S3…) successfully uploaded the output file.

app.upload.failed

A storage upload failed after all retries. Retry or alert from your handler.

How it works

1

Add a Webhook app in ScreenshotCenter

Go to Apps → Connect a new app → Webhooks. Enter your endpoint URL, choose which events to subscribe to, and set a secret for HMAC signature verification.
2

Include the app ID in screenshot requests

Add your webhook app ID to the apps parameter. When the job finishes, ScreenshotCenter sends an HTTP POST to your endpoint.
3

Handle the payload

Your handler receives a signed JSON payload. Verify the X-ScreenshotCenter-Signature header, then process the event however you like. Return 2xx to acknowledge.

Event payload

Every event is delivered as a signed POST request with a JSON body:

POST https://your-server.com/webhooks/screenshot
Content-Type: application/json
X-ScreenshotCenter-Event: screenshot.finished
X-ScreenshotCenter-Signature: sha256=...

{
  "event": "screenshot.finished",
  "screenshot_id": "sc_abc123",
  "url": "https://example.com",
  "status": "finished",
  "image_url": "https://cdn.screenshotcenter.com/sc_abc123.png",
  "width": 1280,
  "height": 720,
  "created_at": "2026-02-22T14:30:00Z",
  "metadata": {}
}

Verifying signatures

ScreenshotCenter signs every webhook with HMAC-SHA256 using the secret you set. Always verify the signature before processing:

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature),
  );
}

// Express handler example
app.post('/webhooks/screenshot', (req, res) => {
  const sig = req.headers['x-screenshotcenter-signature'] as string;
  const raw = JSON.stringify(req.body);

  if (!verifyWebhook(raw, sig, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature');
  }

  const { event, screenshot_id, image_url } = req.body;
  // handle event...
  res.sendStatus(200);
});

Quick start

Reference your webhook app in the apps parameter:

curl "https://api.screenshotcenter.com/api/v1/screenshot/create\
  ?key=YOUR_API_KEY\
  &url=https://example.com\
  &apps=my-webhook-app"

import { ScreenshotCenterClient } from 'screenshotcenter';

const client = new ScreenshotCenterClient(process.env.SCREENSHOTCENTER_API_KEY);

const shot = await client.screenshot.create('https://example.com', {
  apps: ['my-webhook-app'],
});

// Your endpoint receives a POST with the event payload

from screenshotcenter import ScreenshotCenterClient

client = ScreenshotCenterClient(api_key="YOUR_API_KEY")

shot = client.screenshot.create(
    "https://example.com",
    apps=["my-webhook-app"],
)

# Your endpoint receives a POST with the event payload

use ScreenshotCenter\Client;

$client = new Client(getenv('SCREENSHOTCENTER_API_KEY'));

$shot = $client->screenshot->create('https://example.com', [
    'apps' => ['my-webhook-app'],
]);

// Your endpoint receives a POST with the event payload

import sc "github.com/juliensobrier/screenshotcenter-go"

client := sc.New("YOUR_API_KEY")

client.Screenshot.Create("https://example.com", &sc.ScreenshotParams{
    Apps: []string{"my-webhook-app"},
})

// Your endpoint receives a POST with the event payload

require "screenshotcenter"

client = ScreenshotCenter::Client.new(ENV["SCREENSHOTCENTER_API_KEY"])

client.screenshot.create("https://example.com",
  apps: ["my-webhook-app"],
)

# Your endpoint receives a POST with the event payload

import io.screenshotcenter.ScreenshotCenterClient;
import io.screenshotcenter.models.*;
import java.util.List;

public class Main {
    public static void main(String[] args) throws Exception {
        var client = new ScreenshotCenterClient("YOUR_API_KEY");
        client.screenshot().create("https://example.com",
            new ScreenshotParams().apps(List.of("my-webhook-app")));
    }
}

using ScreenshotCenter;

var client = new ScreenshotCenterClient("YOUR_API_KEY");

await client.Screenshot.CreateAsync("https://example.com", new ScreenshotParams {
    Apps = new[] { "my-webhook-app" },
});

// Your endpoint receives a POST with the event payload

Reliability & retries

If your endpoint returns a non-2xx status or times out, ScreenshotCenter retries delivery with exponential backoff — up to 5 attempts. You can inspect delivery status and retry manually from the webhook app settings in the dashboard.

Get started

1. Create a free account on ScreenshotCenter.
2. Go to Apps → Connect a new app → Webhooks. Enter your endpoint URL and a signing secret.
3. Subscribe to the events you need and save. Copy the app ID.
4. Add the app ID to the apps parameter in your screenshot requests.
5. Verify the X-ScreenshotCenter-Signature header in your handler and return 200 OK.

Get started free API reference All integrations