Webhooks API — GoScreenAPI

One Webhook, Seven Event Types

Q: How do I verify the webhook signature?

Compute HMAC-SHA256 over the RAW request body with your subscription secret, prefix the hex digest with "sha256=", and compare against the X-GoScreen-Signature header using a constant-time comparison (e.g. crypto.timingSafeEqual in Node.js, hmac.compare_digest in Python, hash_equals in PHP). Critical: capture the raw bytes BEFORE any JSON parsing.

Q: What is the retry policy when my server is down?

Four total attempts: immediately on the first try, then +1 minute, +10 minutes, and +1 hour. Each attempt mutates the same delivery row (attempt_no increments, status becomes retrying). After the fourth failure status becomes failed and you can force-retry from the dashboard.

Q: Which response codes count as success?

Any 2xx HTTP response within 30 seconds. Anything else (3xx, 4xx, 5xx, timeout, DNS failure, connect refused) triggers the retry schedule.

Q: How do I avoid processing duplicate deliveries?

Each delivery carries an X-GoScreen-Delivery header with a stable UUID across retries. Store seen UUIDs (e.g. in Redis with a 24h TTL) and skip duplicates. The same logical delivery never gets a new UUID, even after manual force-retry.

Q: How many active subscriptions can I have?

Up to 10 active subscriptions per account. You can have unlimited inactive ones; only active subscriptions receive events.

Q: Does this replace the legacy webhook_url parameter on screenshot requests?

No. The legacy per-request webhook_url + webhook_secret on /api/v1/screenshot is fully supported and unchanged. The Webhooks API adds an additional, generic, multi-event subscription system on top. Both can run in parallel.

Q: Can I receive events for a different user?

No. Each subscription is owned by one user; the dispatcher enforces strict user_id isolation. There is no team-shared subscription mode at this time.

Q: Where do I create a subscription?

Sign in and visit /dashboard/webhook-subscriptions, click "New Webhook", paste your endpoint URL, pick events, and copy the secret shown once. The dashboard also exposes test, retry, rotate-secret and delivery-history actions.

Subscribe once, receive every event the GoScreenAPI platform produces — screenshots, visual diffs, price changes, uptime alerts, crawl completions, and AI agent runs — all signed with HMAC-SHA256 and retried up to four times.

Get API Key → View Docs

✓ 250 free screenshots/month ✓ No credit card required ✓ REST API · JSON

javascript

// Express.js webhook receiver — verify the signature and process the event
const crypto = require('crypto');
const express = require('express');

app.post('/webhooks/goscreen', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-goscreen-signature'] || '';
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.GOSCREEN_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).end();
  }

  const event = JSON.parse(req.body.toString());
  console.log(event.event, event.data);  // e.g. "screenshot.completed"
  res.status(200).end();
});

Features

Everything you need.
Nothing you don't.

Seven Event Types

screenshot.completed, visual.diff_detected, price.changed, uptime.down, uptime.up, crawl.completed, ai_agent.completed.

HMAC-SHA256 Signed

Every request carries an X-GoScreen-Signature header. Verify it in any language with the standard library.

Smart Retries

Four attempts at increasing backoff (immediate, +1m, +10m, +1h). One delivery row per attempt history.

Per-User Subscriptions

Each subscription is yours alone. Multi-tenant isolation enforced at the dispatcher boundary.

Test & Replay

Fire a synthetic test event from the dashboard. Failed deliveries can be force-retried with one click.

Rotatable Secrets

Rotate the signing secret without losing delivery history. Old secret stops working immediately.

Use Cases

Built for real workflows

From solo developers to enterprise teams — GoScreenAPI fits into any stack.

Slack & Discord Bots

Post screenshot results, uptime alerts, or price drops to a channel as soon as they happen.

AI Pipelines

Trigger downstream LLM workflows when a screenshot or crawl finishes — no polling required.

Custom Dashboards

Stream events to your own database for custom analytics, internal tooling, or audit logs.

Zapier / Make / n8n

Plug GoScreenAPI events into 6,000+ apps via standard webhook nodes.

API Reference

Key Parameters

Full reference at goscreenapi.com/docs

Parameter	Type	Description
`url`	string	Your HTTPS endpoint that receives POST requests
`event_types`	array	Subset of the seven canonical event types to listen for
`description`	string	Optional human label for the subscription
`is_active`	boolean	Toggle without deleting; defaults to true
`X-GoScreen-Signature`	header	sha256=<hex(hmac_sha256(secret, raw_body))> — verify on receiver
`X-GoScreen-Event`	header	Canonical event type, e.g. screenshot.completed

View full API reference →

Why GoScreenAPI

Speed. Scale. Simplicity.

< 3s

Avg. response time

Sync mode results in under 3 seconds for most pages.

99.9%

Uptime SLA

Production-grade reliability with redundant infrastructure.

150 req/min

Rate limit (Pro)

Handle high-volume workloads without throttling.

FAQ

Common questions