Webhooks

Real-time event notifications

Webhooks allow you to receive real-time notifications when events occur in your SnapshotAI account. Configure webhook endpoints to get instant updates when screenshots complete, fail, or are queued.

How Webhooks Work

1. Subscribe

Create a webhook endpoint and select which events you want to receive.

2. Event Occurs

When an event happens, we immediately send a POST request to your URL.

3. Process

Your endpoint receives the payload and processes it in your application.

Why Use Webhooks?

Webhooks are more efficient than polling. Instead of repeatedly checking for updates, you receive instant notifications when events occur, reducing API calls and improving response times.

Available Events

screenshot.queuedScreenshot

Triggered when a screenshot job is created and queued for processing

screenshot.completedScreenshot

Triggered when a screenshot job completes successfully

screenshot.failedScreenshot

Triggered when a screenshot job fails to complete

video.completedVideo

Triggered when a video recording job completes successfully

video.failedVideo

Triggered when a video recording job fails to complete

POST

/v1/webhooks

Create a new webhook endpoint to receive event notifications. Your endpoint must be accessible via HTTPS and return a 2xx status code within 5 seconds.

Base URL: https://www.snapshotai.dev

HTTPS Required

Webhook URLs must use HTTPS for security. HTTP endpoints will be rejected.

Request Body

namestringRequired

Descriptive name for the webhook endpoint (max 100 characters)

Example: Production Webhook

urlstringRequired

HTTPS URL where webhook events will be sent. Must start with https://

Example: https://your-app.com/api/webhooks/screenshot

eventsarray<string>Required

Array of event types to subscribe to. At least one event required.

Example: ["screenshot.completed", "screenshot.failed"]

descriptionstringOptional

Optional description of webhook purpose (max 500 characters)

Example: Notifies production system when screenshots complete

is_activebooleanOptional

Whether webhook is active and should receive events

Default: true

Example

Create Webhook•bash

curl -X POST https://www.snapshotai.dev/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Webhook",
    "url": "https://your-app.com/api/webhooks/screenshot",
    "events": ["screenshot.completed", "screenshot.failed"],
    "description": "Notifies when screenshots complete or fail"
  }'

Success Response

201 Createdapplication/json

{
  "message": "Webhook endpoint created successfully",
  "data": {
    "id": "wh_abc123xyz",
    "name": "Production Webhook",
    "url": "https://your-app.com/api/webhooks/screenshot",
    "events": [
      "screenshot.completed",
      "screenshot.failed"
    ],
    "description": "Notifies when screenshots complete or fail",
    "is_active": true,
    "is_default": false,
    "created_at": "2025-11-04T23:45:30.123Z",
    "updated_at": "2025-11-04T23:45:30.123Z"
  }
}

GET

/v1/webhooks

List all your webhook endpoints with filtering and pagination.

Base URL: https://www.snapshotai.dev

Query Parameters

include_inactivebooleanOptional

Include inactive webhooks in results

Default: false

limitnumberOptional

Maximum number of results to return

Default: 100

offsetnumberOptional

Number of results to skip for pagination

Default: 0

GET

/v1/webhooks/:id

Get detailed information about a specific webhook endpoint, including delivery statistics.

Base URL: https://www.snapshotai.dev

Path Parameters

idstringRequired

The unique identifier of the webhook (starts with wh_)

PATCH

/v1/webhooks/:id

Update webhook endpoint configuration. You can change the URL, events, or enable/disable the webhook.

Base URL: https://www.snapshotai.dev

Request Body

namestringOptional

Update webhook name

Example: Updated Webhook Name

urlstringOptional

Update webhook URL (must be HTTPS)

Example: https://new-endpoint.com/webhooks

eventsarray<string>Optional

Update subscribed events

Example: ["screenshot.completed"]

is_activebooleanOptional

Enable or disable webhook

Example: false

DELETE

/v1/webhooks/:id

Permanently delete a webhook endpoint. This action cannot be undone.

Base URL: https://www.snapshotai.dev

Success Response

204 No Content

Empty response body. Webhook successfully deleted.

POST

/v1/webhooks/:id/test

Send a test event to your webhook endpoint to verify it's working correctly.

Base URL: https://www.snapshotai.dev

Test Delivery

The test sends a sample screenshot.completed event with dummy data to verify your endpoint responds correctly.

Example

Test Webhook•bash

curl -X POST https://www.snapshotai.dev/api/v1/webhooks/wh_abc123xyz/test \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response

200 OKapplication/json

{
  "success": true,
  "message": "Webhook test successful",
  "status_code": 200,
  "response_time_ms": 142,
  "error": null,
  "timestamp": "2025-11-04T23:50:15.456Z"
}

Webhook Payload

All webhook events have a consistent structure with event metadata and relevant data:

Webhook Payload Structure•json

{
  "id": "evt_2nX8Kp9mJ4dL7qR",
  "type": "screenshot.completed",
  "created_at": "2025-11-04T23:30:19.654Z",
  "data": {
    "screenshot": {
      "id": "scr_2nX8Kp9mJ4dL7qR",
      "url_to_capture": "https://example.com",
      "status": "completed",
      "storage_path": "users/usr_abc123/scr_2nX8Kp9mJ4dL7qR.png",
      "file_size_bytes": 245678,
      "processing_duration_ms": 3420,
      "download_url": "https://storage.snapshotai.dev/...",
      "created_at": "2025-11-04T23:30:15.123Z",
      "completed_at": "2025-11-04T23:30:19.654Z",
      "options": {
        "viewport_width": 1920,
        "viewport_height": 1080,
        "format": "png"
      }
    }
  }
}

id

Unique event identifier for deduplication

type

Event type (e.g., screenshot.completed)

data

Event-specific data (screenshot, video, etc.)

Security & Verification

Verify webhook authenticity using the signature in the X-Webhook-Signature header:

Signature Verification•javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Express.js middleware
app.post('/api/webhooks/screenshot', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = req.body;
  
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process webhook
  const { type, data } = payload;
  
  if (type === 'screenshot.completed') {
    console.log('Screenshot completed:', data.screenshot.id);
    console.log('Download URL:', data.screenshot.download_url);
  }
  
  res.status(200).json({ received: true });
});

Security Best Practices

• Always verify webhook signatures before processing
• Use HTTPS endpoints only
• Implement idempotency using the event id
• Return 2xx status codes quickly, process async if needed
• Store your webhook secret securely in environment variables

Best Practices

• Respond quickly - Return 200 within 5 seconds to avoid retries
• Process async - Queue webhook processing for heavy tasks
• Use idempotency - Track event IDs to handle duplicate deliveries
• Handle failures gracefully - We retry failed deliveries up to 3 times
• Monitor delivery stats - Check webhook endpoint statistics regularly
• Test thoroughly - Use the test endpoint before going live

Retry Policy

If your endpoint fails to respond with a 2xx status code, we automatically retry:

First Retry

After 1 minute

Second Retry

After 5 minutes

Final Retry

After 15 minutes

After 3 failed attempts, the webhook delivery is marked as failed and no further retries occur.

Related Resources

Screenshot API →Manage Webhooks →Error Handling →

How Webhooks Work

1. Subscribe

Create a webhook endpoint and select which events you want to receive.

2. Event Occurs

When an event happens, we immediately send a POST request to your URL.

3. Process

Your endpoint receives the payload and processes it in your application.

Why Use Webhooks?

Webhooks are more efficient than polling. Instead of repeatedly checking for updates, you receive instant notifications when events occur, reducing API calls and improving response times.

Available Events

screenshot.queuedScreenshot

Triggered when a screenshot job is created and queued for processing

screenshot.completedScreenshot

Triggered when a screenshot job completes successfully

screenshot.failedScreenshot

Triggered when a screenshot job fails to complete

video.completedVideo

Triggered when a video recording job completes successfully

video.failedVideo

Triggered when a video recording job fails to complete

curl -X POST https://www.snapshotai.dev/api/v1/webhooks \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Production Webhook", "url": "https://your-app.com/api/webhooks/screenshot", "events": ["screenshot.completed", "screenshot.failed"], "description": "Notifies when screenshots complete or fail" }'

{ "message": "Webhook endpoint created successfully", "data": { "id": "wh_abc123xyz", "name": "Production Webhook", "url": "https://your-app.com/api/webhooks/screenshot", "events": [ "screenshot.completed", "screenshot.failed" ], "description": "Notifies when screenshots complete or fail", "is_active": true, "is_default": false, "created_at": "2025-11-04T23:45:30.123Z", "updated_at": "2025-11-04T23:45:30.123Z" } }

Webhook Payload

All webhook events have a consistent structure with event metadata and relevant data:

Webhook Payload Structure•json

{
  "id": "evt_2nX8Kp9mJ4dL7qR",
  "type": "screenshot.completed",
  "created_at": "2025-11-04T23:30:19.654Z",
  "data": {
    "screenshot": {
      "id": "scr_2nX8Kp9mJ4dL7qR",
      "url_to_capture": "https://example.com",
      "status": "completed",
      "storage_path": "users/usr_abc123/scr_2nX8Kp9mJ4dL7qR.png",
      "file_size_bytes": 245678,
      "processing_duration_ms": 3420,
      "download_url": "https://storage.snapshotai.dev/...",
      "created_at": "2025-11-04T23:30:15.123Z",
      "completed_at": "2025-11-04T23:30:19.654Z",
      "options": {
        "viewport_width": 1920,
        "viewport_height": 1080,
        "format": "png"
      }
    }
  }
}

id

Unique event identifier for deduplication

type

Event type (e.g., screenshot.completed)

data

Event-specific data (screenshot, video, etc.)

Security & Verification

Verify webhook authenticity using the signature in the X-Webhook-Signature header:

Signature Verification•javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Express.js middleware
app.post('/api/webhooks/screenshot', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = req.body;
  
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process webhook
  const { type, data } = payload;
  
  if (type === 'screenshot.completed') {
    console.log('Screenshot completed:', data.screenshot.id);
    console.log('Download URL:', data.screenshot.download_url);
  }
  
  res.status(200).json({ received: true });
});

Security Best Practices

• Always verify webhook signatures before processing
• Use HTTPS endpoints only
• Implement idempotency using the event id
• Return 2xx status codes quickly, process async if needed
• Store your webhook secret securely in environment variables