Async & Webhooks

Process screenshots asynchronously without waiting for the render to complete. Receive results via webhook when ready.

Async Rendering

Set async=true to process requests in the background. The API validates your request and returns immediately while rendering continues asynchronously.

https://api.lambdashot.com/take?url=https://example.com&async=true&store=true&storage_path=screenshots/example.png&access_key=YOUR_KEY

Note: Async mode is typically used with S3 storage upload (store=true) or webhooks to receive the result.

Webhooks

Receive the screenshot result at your specified URL when rendering completes. LambdaShot sends a POST request with the result as JSON.

Parameters

Parameter	Description	Default
webhook_url	URL to receive the webhook POST	—
webhook_sign	Sign webhook with HMAC-SHA256	true
webhook_errors	Send webhook on errors too	false
external_identifier	Your custom tracking ID (returned in webhook)	—

Example Request

https://api.lambdashot.com/take?url=https://example.com&async=true&store=true&storage_path=example.png&webhook_url=https://yoursite.com/webhook&storage_return_location=true&access_key=YOUR_KEY

Webhook Payload

On success, your webhook receives a POST with this JSON body:

{
  "is_successful": true,
  "screenshot_url": "https://cdn.lambdashot.com/...",
  "store": {
    "location": "https://your-bucket.s3.amazonaws.com/example.png"
  },
  "external_identifier": "your-tracking-id"
}

On error (if webhook_errors=true):

{
  "is_successful": false,
  "error": {
    "code": "timeout_error",
    "message": "The screenshot timed out."
  },
  "external_identifier": "your-tracking-id"
}

Webhook Signature Verification

When webhook_sign=true (default), LambdaShot signs the webhook using HMAC-SHA256 with your secret key. The signature is sent in the X-LambdaShot-Signature header.

To verify the signature:

1. Get the raw request body
2. Compute HMAC-SHA256 using your secret key
3. Compare with the X-LambdaShot-Signature header

Verification Example (Node.js)

const crypto = require('crypto');

function verifyWebhook(body, signature, secretKey) {
  const expectedSignature = crypto
    .createHmac('sha256', secretKey)
    .update(body)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-lambdashot-signature'];
  const isValid = verifyWebhook(req.rawBody, signature, 'YOUR_SECRET_KEY');

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook...
  res.sendStatus(200);
});

Response Headers

Async responses include useful debugging headers:

Header	Description
x-lambdashot-rendering-seconds	Time taken to render
x-lambdashot-size-bytes	Screenshot file size
x-lambdashot-trace-id	Request ID for support
x-lambdashot-reference	Screenshot/video reference ID
x-lambdashot-external-identifier	Your custom tracking ID

Use Cases

• Batch processing — Queue many screenshots without blocking
• S3 upload — Upload directly to your storage without downloading first
• Long renders — Avoid timeouts on complex pages
• Microservices — Decouple screenshot generation from your main app