WebsiteScreenshotWorld 0.4.0

dotnet add package WebsiteScreenshotWorld --version 0.4.0
                    
NuGet\Install-Package WebsiteScreenshotWorld -Version 0.4.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="WebsiteScreenshotWorld" Version="0.4.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="WebsiteScreenshotWorld" Version="0.4.0" />
                    
Directory.Packages.props
<PackageReference Include="WebsiteScreenshotWorld" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add WebsiteScreenshotWorld --version 0.4.0
                    
#r "nuget: WebsiteScreenshotWorld, 0.4.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package WebsiteScreenshotWorld@0.4.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=WebsiteScreenshotWorld&version=0.4.0
                    
Install as a Cake Addin
#tool nuget:?package=WebsiteScreenshotWorld&version=0.4.0
                    
Install as a Cake Tool

Website Screenshot World for .NET

The official .NET client for Website Screenshot World. Capture web pages as images, videos or PDFs with Instant Snap, start scheduled captures with Auto Schedule, and verify the webhooks both products send.

dotnet add package WebsiteScreenshotWorld

Using Microsoft.Extensions.DependencyInjection (ASP.NET Core, worker services)? Add the integration package as well; see Dependency injection.

dotnet add package WebsiteScreenshotWorld.Extensions.DependencyInjection

Quick start

Create an API key for each product you use in the dashboard. The client reads them from the WSW_INSTANT_SNAP_API_KEY and WSW_AUTO_SCHEDULE_API_KEY environment variables, or you can pass them in.

using WebsiteScreenshotWorld;
using WebsiteScreenshotWorld.InstantSnap;

using var client = new WebsiteScreenshotWorldClient();

var capture = await client.InstantSnap.CaptureAsync(new CaptureOptions
{
    Url = "https://example.com",
    Format = CaptureFormat.WebP,
    Viewport = new Viewport { Width = 1440, Height = 900 },
    ScrollMode = ScrollMode.Scroll,
});

Console.WriteLine($"{capture.Id}: {capture.Width}x{capture.Height}, {capture.SizeBytes} bytes");
Console.WriteLine($"Download within the hour: {capture.DownloadUrl}");

Create one client and reuse it: it is safe to share between threads, and it keeps connections open between calls.

Options you leave unset are not sent, so the API applies its defaults (await client.InstantSnap.GetDefaultsAsync() lists them). false, 0 and empty strings are sent as values.

Auto Schedule

Web pages are scheduled in the dashboard. TriggerNowAsync captures one now, and the result arrives by webhook. Calling it again while a capture is pending starts nothing new.

using WebsiteScreenshotWorld.AutoSchedule;

var result = await client.AutoSchedule.TriggerNowAsync(Guid.Parse("7d4e2b1a-6c5f-4a3e-9d8c-2b1a0f9e8d7c"));

if (result.Status == TriggerStatus.AlreadyPending)
{
    Console.WriteLine($"Already queued at {result.TriggeredAt:u}.");
}

Captures

Save the file straight away

CaptureFileAsync returns the file in the response. It is streamed, not held in memory, and the API does not keep a copy, so save or read it and then dispose it.

await using var file = await client.InstantSnap.CaptureFileAsync(new CaptureOptions
{
    Url = "https://example.com",
    MediaCategory = MediaCategory.Pdf,
    Format = CaptureFormat.DocumentPdf,
});

await file.SaveToAsync(file.FileName ?? "capture.pdf");
Console.WriteLine($"{file.ContentType}, {file.SizeBytes} bytes, SHA-256 {file.Sha256}");

file.Content is the raw Stream if you would rather copy it somewhere yourself, for example into a blob upload.

Upload to your own bucket

CaptureToBucketAsync uploads the file to any S3-compatible bucket. Set Region for AWS or EndpointUrl for other providers.

var capture = await client.InstantSnap.CaptureToBucketAsync(new CaptureOptions
{
    Url = "https://example.com",
    S3Delivery = new S3DeliveryOptions
    {
        AccessKeyId = Environment.GetEnvironmentVariable("AWS_ACCESS_KEY_ID"),
        SecretAccessKey = Environment.GetEnvironmentVariable("AWS_SECRET_ACCESS_KEY"),
        Bucket = "my-captures",
        Region = "eu-west-2",
        KeyPrefix = "homepage/",
        WaitForSync = true,
    },
});

Console.WriteLine($"Upload {capture.S3Delivery?.Status}: {capture.S3Delivery?.Key}");

Read a capture back

Files are kept for 24 hours and a download link lasts 60 minutes. GetAsync returns the capture with a fresh link, and DownloadAsync saves the file to a path or a stream.

var latest = await client.InstantSnap.GetAsync(capture.Id);

if (latest.Status == CaptureStatus.Succeeded)
{
    await client.InstantSnap.DownloadAsync(latest, "homepage.png");
}

Async captures

SubmitAsync and SubmitToBucketAsync queue a capture and return at once (HTTP 202) with the capture in CaptureStatus.Queued; it moves to Running when a browser is free, then succeeds or fails. WaitAsync reads it every 3 seconds until it has finished and returns it. If it is still unfinished when the wait runs out (360 seconds by default) you get the capture as last read rather than an exception, so check Status and wait again if you like.

var queued = await client.InstantSnap.SubmitAsync(new CaptureOptions
{
    Url = "https://example.com",
    TimeoutSeconds = 240,
});

var finished = await client.InstantSnap.WaitAsync(
    queued.Id,
    timeout: TimeSpan.FromMinutes(10),
    pollInterval: TimeSpan.FromSeconds(5),
    cancellationToken: cancellationToken);

if (finished.Status == CaptureStatus.Succeeded)
{
    await client.InstantSnap.DownloadAsync(finished, "homepage.png");
}

var upload = await client.InstantSnap.SubmitToBucketAsync(new CaptureOptions
{
    Url = "https://example.com",
    S3Delivery = new S3DeliveryOptions { AccessKeyId = "...", SecretAccessKey = "...", Bucket = "my-captures", Region = "eu-west-2" },
});
  • TimeoutSeconds (sent as timeout) is the browser time the capture may use, 30 to 300 seconds; the API uses 120 when it is not set, and refuses it on the other capture methods. It is not RequestOptions.Timeout, which is how long the client waits for an answer: submitting takes the ordinary 30-second timeout, since nothing runs while you wait.
  • A capture still queued 15 minutes after it was accepted ends failed with capture_expired and is not charged.
  • When your organization already has as many async captures waiting or running as it may, the submit is refused with queue_full, raised as a RateLimitException whose RetryAfter says when to try again. It is not retried.
  • Instead of waiting you can call GetAsync yourself, or pass a CallbackUrl and take the webhook.

Everything else a capture can do

var detailed = await client.InstantSnap.CaptureAsync(new CaptureOptions
{
    Url = "https://example.com/pricing",
    DeviceCategory = DeviceCategory.Mobile,
    EmulatedDevice = "Pixel 7",
    BlockAds = false,
    Locale = "en-GB",
    TimeZone = "Europe/London",
    Headers = new Dictionary<string, string> { ["X-Preview"] = "1" },
    Cookies = new Dictionary<string, string> { ["theme"] = "dark" },
    Geolocation = new Geolocation { Latitude = 51.5072, Longitude = -0.1276 },
    Selectors = new Selectors { Hide = ".cookie-banner" },
    Proxy = new ProxyOptions { Country = "gb" },
    TimestampWatermark = new TimestampWatermark { Location = WatermarkLocation.Bottom },
    PageSource = new PageSourceOptions { Format = PageSourceFormat.Html },
    CallbackUrl = "https://example.com/webhooks/website-screenshot-world",
});

var catalog = await client.InstantSnap.GetCatalogAsync();
Console.WriteLine(string.Join(", ", catalog.EmulatedDevices));

GetAccountAsync answers whose key the client holds, without the key itself and without spending a capture (client.AutoSchedule.GetAccountAsync() does the same for the Auto Schedule key):

var account = await client.InstantSnap.GetAccountAsync();
Console.WriteLine($"{account.Email} ({account.KeyName}, {account.KeyPrefix})");

Header and cookie names are sent exactly as you write them. Values such as CaptureFormat and CaptureStatus are small structs rather than enums, so a value the API adds later still comes through; compare them with the static properties (capture.Status == CaptureStatus.Failed).

Errors and retries

Every error derives from WebsiteScreenshotWorldException. A refusal from the API carries its ErrorCode, StatusCode, RetryAfter and the raw ResponseBody, and is raised as the subclass for its kind:

Exception Error codes
AuthenticationException api_key_invalid
InvalidRequestException validation_failed, s3_destination_invalid, web_page_id_invalid, idempotency_key_reused, sitemap_schedule_not_triggerable
PlanLimitException quota_exhausted, feature_not_available, no_trigger_allowance, forbidden
NotFoundException capture_not_found, web_page_not_found, not_found
RateLimitException rate_limited, queue_full
CaptureException capture_failed, capture_timeout, payload_too_large, capture_expired
ServiceException capture_busy, service_unavailable, internal_error, request_cancelled, idempotency_key_in_use
WebsiteScreenshotWorldConnectionException none: no answer came back (see InnerException)
WebsiteScreenshotWorldException a code this version does not know yet

Decide what to do from ErrorCode; the status and the message can change.

try
{
    await client.InstantSnap.CaptureAsync(new CaptureOptions { Url = "https://example.com" });
}
catch (CaptureException e) when (e.ErrorCode == "capture_timeout")
{
    Console.WriteLine("The page took too long; try a longer PageTimeoutMs.");
}
catch (PlanLimitException e)
{
    Console.WriteLine($"Plan limit: {e.ErrorCode}");
}
catch (WebsiteScreenshotWorldConnectionException e)
{
    Console.WriteLine($"No answer: {e.InnerException?.Message}");
}
catch (WebsiteScreenshotWorldException e)
{
    Console.WriteLine($"{e.ErrorCode} (HTTP {(int?)e.StatusCode}): {e.Message}");
}

A call with no API key for its product throws InvalidOperationException before anything is sent.

The client retries rate_limited, capture_busy, service_unavailable and idempotency_key_in_use answers, and connection failures, up to twice (MaxRetries). It waits as long as the API asks, up to 60 seconds, or otherwise 0.5 seconds and then 1 second with a little jitter. Nothing else is retried: a capture_failed page will fail the same way again, and a queue_full queue will still be full, so it is raised with RetryAfter for you. Cancelling the CancellationToken stops at once, retries included.

Idempotency keys

Every capture sends an Idempotency-Key, so a retry never captures twice. The client makes a new one per call and reuses it on that call's retries. Pass your own to make a capture safe to repeat across calls or processes: within 24 hours, the same key returns the first capture instead of taking another.

var order = await client.InstantSnap.CaptureAsync(
    new CaptureOptions { Url = "https://example.com/order/1234" },
    new RequestOptions { IdempotencyKey = "order-1234-receipt" });

Timeouts and cancellation

A capture may take 180 seconds, since the API can spend up to 120 seconds on a slow page, and any other call, including SubmitAsync and SubmitToBucketAsync, 30 seconds. The time covers the whole call, retries and the waits between them included, until the answer starts to arrive; reading a file from CaptureFileAsync afterwards is not timed. Change them for the client, or for one call:

var quick = await client.InstantSnap.CaptureAsync(
    new CaptureOptions { Url = "https://example.com" },
    new RequestOptions { Timeout = TimeSpan.FromSeconds(60) },
    cancellationToken);

A call that runs out of time is not retried: it is raised as WebsiteScreenshotWorldConnectionException with a TimeoutException inside. A retry whose wait would run past the time is not started; the refusal is raised instead. Cancelling your token raises OperationCanceledException as usual.

A render link is a signed URL that is itself a screenshot, for an <img> tag, an email or a social preview. RenderLink.Build makes one locally - nothing is sent and no client is needed - from the key's render secret (shown on the dashboard's API Keys page once render links are on for the key) and its 12-character prefix:

using WebsiteScreenshotWorld.InstantSnap;
using WebsiteScreenshotWorld.RenderLinks;

var src = RenderLink.Build(new RenderLinkOptions
{
    RenderSecret = Environment.GetEnvironmentVariable("WSW_RENDER_SECRET"),
    KeyPrefix = "0123456789ab",
    Url = "https://example.com",
    Format = CaptureFormat.WebP,
    Width = 1280,
    Height = 720,
    ThumbWidth = 400,
    TtlSeconds = 86_400, // serve the same capture for a day
});
// <img src="@src" alt="example.com">

A view of the link that is not cached makes one capture from your plan; cached views are free. Keep the render secret on your server: anyone who has it can make links that use your captures. Render links are on the Pro, Business and Business Plus plans.

Webhooks

Deliveries carry an X-WSW-Signature header. Webhook.Verify checks it against your endpoint's signing secret, refuses a timestamp more than five minutes from now, and returns the event typed by its type:

Event Type Data
Instant Snap capture.succeeded / capture.failed InstantSnapCaptureSucceededEvent / InstantSnapCaptureFailedEvent Capture
Auto Schedule capture.succeeded / capture.failed ScheduledCaptureSucceededEvent / ScheduledCaptureFailedEvent ScheduledCapture
delivery.completed DeliveryCompletedEvent DeliveredCapture
capture.changed CaptureChangedEvent ChangedCapture
schedule.paused SchedulePausedEvent SchedulePause
sitemap_run.completed SitemapRunCompletedEvent SitemapRun
ping PingEvent WebhookPing
a type added later UnknownWebhookEvent JsonElement

Verify the body exactly as received. If your framework parses the JSON and you serialise it again, the bytes change and the signature no longer matches, so read the raw request body as shown below. A failed check throws SignatureVerificationException; answer it with 400.

ASP.NET Core minimal APIs

using WebsiteScreenshotWorld;
using WebsiteScreenshotWorld.Webhooks;

app.MapPost("/webhooks/website-screenshot-world", async (HttpRequest request, IConfiguration configuration) =>
{
    using var body = new MemoryStream();
    await request.Body.CopyToAsync(body);

    WebhookEvent webhookEvent;
    try
    {
        webhookEvent = Webhook.Verify(
            body.ToArray(),
            request.Headers[Webhook.SignatureHeaderName].ToString(),
            configuration["WebsiteScreenshotWorld:WebhookSecret"]!);
    }
    catch (SignatureVerificationException)
    {
        return Results.BadRequest();
    }

    switch (webhookEvent)
    {
        case InstantSnapCaptureSucceededEvent succeeded:
            Console.WriteLine($"Capture {succeeded.Data.Id} is ready.");
            break;
        case ScheduledCaptureFailedEvent failed:
            Console.WriteLine($"{failed.Data.ScheduleName} failed with HTTP {failed.Data.PageHttpStatus}.");
            break;
        case CaptureChangedEvent changed:
            Console.WriteLine($"{changed.Data.Url} changed by {changed.Data.ChangePercent}%.");
            break;
    }

    return Results.Ok();
});

ASP.NET Core MVC controllers

Do not bind the body to a [FromBody] parameter; read Request.Body yourself.

using Microsoft.AspNetCore.Mvc;
using WebsiteScreenshotWorld;
using WebsiteScreenshotWorld.Webhooks;

[ApiController]
[Route("webhooks/website-screenshot-world")]
public sealed class WebsiteScreenshotWorldWebhookController(IConfiguration configuration) : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> Receive()
    {
        using var body = new MemoryStream();
        await Request.Body.CopyToAsync(body, HttpContext.RequestAborted);

        try
        {
            var webhookEvent = Webhook.Verify(
                body.ToArray(),
                Request.Headers[Webhook.SignatureHeaderName].ToString(),
                configuration["WebsiteScreenshotWorld:WebhookSecret"]!);

            if (webhookEvent is DeliveryCompletedEvent delivered)
            {
                foreach (var destination in delivered.Data.Destinations)
                {
                    Console.WriteLine($"{destination.Name}: {destination.Status}");
                }
            }

            return Ok();
        }
        catch (SignatureVerificationException)
        {
            return BadRequest();
        }
    }
}

Azure Functions (isolated worker)

using System.Net;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using WebsiteScreenshotWorld;
using WebsiteScreenshotWorld.Webhooks;

public sealed class WebsiteScreenshotWorldWebhook
{
    [Function("WebsiteScreenshotWorldWebhook")]
    public async Task<HttpResponseData> Run([HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequestData request)
    {
        using var body = new MemoryStream();
        await request.Body.CopyToAsync(body);
        var signature = request.Headers.TryGetValues(Webhook.SignatureHeaderName, out var values) ? values.First() : "";

        try
        {
            var webhookEvent = Webhook.Verify(body.ToArray(), signature, Environment.GetEnvironmentVariable("WSW_WEBHOOK_SECRET")!);
            if (webhookEvent is SchedulePausedEvent paused)
            {
                Console.WriteLine($"{paused.Data.ScheduleName} paused: {paused.Data.Reason}");
            }

            return request.CreateResponse(HttpStatusCode.OK);
        }
        catch (SignatureVerificationException)
        {
            return request.CreateResponse(HttpStatusCode.BadRequest);
        }
    }
}

Webhook.Verify also accepts the body as a string, a custom tolerance, and a now for tests.

Dependency injection

AddWebsiteScreenshotWorld registers WebsiteScreenshotWorldClient as a typed client, so its HttpClient comes from IHttpClientFactory. It returns the IHttpClientBuilder, so you can add handlers as with any typed client.

builder.Services.AddWebsiteScreenshotWorld(options =>
{
    options.InstantSnapApiKey = builder.Configuration["WebsiteScreenshotWorld:InstantSnapApiKey"];
    options.AutoScheduleApiKey = builder.Configuration["WebsiteScreenshotWorld:AutoScheduleApiKey"];
});

Or bind every setting from configuration:

builder.Services.AddWebsiteScreenshotWorld();
builder.Services.Configure<WebsiteScreenshotWorldClientOptions>(builder.Configuration.GetSection("WebsiteScreenshotWorld"));

Then take WebsiteScreenshotWorldClient in a constructor. The client already retries, so do not add a retry handler on top. Its handler does not follow redirects; if you replace the primary handler, keep AllowAutoRedirect = false on yours.

If you pass your own HttpClient to the constructor instead, set its Timeout to Timeout.InfiniteTimeSpan: the client applies its own, longer timeouts, and the default of 100 seconds would cut long captures short. Turn redirects off in its handler too:

var http = new HttpClient(new SocketsHttpHandler { AllowAutoRedirect = false }) { Timeout = Timeout.InfiniteTimeSpan };
using var client = new WebsiteScreenshotWorldClient(http);

A handler that follows a redirect sends the API key on to wherever it points. Neither the API nor a download link redirects, so the client refuses any answer that came through a redirect, but by then the key has been sent.

Configuration

WebsiteScreenshotWorldClientOptions Default
InstantSnapApiKey the WSW_INSTANT_SNAP_API_KEY environment variable
AutoScheduleApiKey the WSW_AUTO_SCHEDULE_API_KEY environment variable
InstantSnapBaseUrl https://api.websitescreenshotworld.com
AutoScheduleBaseUrl https://autoapi.websitescreenshotworld.com
CaptureTimeout 180 seconds per call, retries included
Timeout 30 seconds per call, retries included, for everything but synchronous captures (async submits use it)
MaxRetries 2, so at most 3 attempts

Either key may be left out if you only use the other product. GetDefaultsAsync needs no key.

Supported runtimes

.NET 8 and later, tested on .NET 8 and .NET 10. The package also carries a .NET Standard 2.0 build for .NET Framework 4.6.2 and later and other runtimes that implement it.

Development

The tests play the shared cases in spec/ through spec/conformance/server.js, so they need Node.js 22 or later on the PATH. spec/ is the websitescreenshotworld-spec submodule: clone with git clone --recurse-submodules, or run git submodule update --init in an existing clone.

dotnet test
dotnet format --verify-no-changes

License

MIT. See LICENSE.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on WebsiteScreenshotWorld:

Package Downloads
WebsiteScreenshotWorld.Extensions.DependencyInjection

Registers the Website Screenshot World client with Microsoft.Extensions.DependencyInjection as a typed HttpClient.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.4.0 126 11/15/2026
0.3.0 129 11/15/2026
0.2.0 126 11/15/2026
0.1.0 126 11/10/2026