StockSweep StockSweep | Help Center

API & Webhooks Setup

Create an API key, subscribe to webhooks, verify signatures, and handle rate limits, retries and key rotation without dropping events.

Last updated: September 22, 2026

Contents
Show all sections (20) ▼

The Public API lets your own systems read and write StockSweep data; webhooks push events to you as they happen. This is the most technical surface in the product, so the specifics — limits, signatures, retry behaviour — are all stated exactly.

Estimated time: 8 minutes

What you'll accomplish

  • Create and safely store an API key
  • Subscribe to webhook events and verify their signatures
  • Understand rate limits, retries and auto-pause
  • Rotate a key without downtime

Requirements

  • Plan: Enterprise. API keys and webhook subscriptions are both 0 on Free, Growth and Pro.
  • Enterprise allows up to 10 API keys and 20 webhook subscriptions.
  • Found at Settings → Integrations → API & Webhooks.

Create an API key

  1. Open Settings → Integrations → API & Webhooks → API keys.
  2. Select Create API key and give it a name that identifies the system using it.
  3. Copy the secret when it is shown.

The secret is shown once. It is stored hashed with a server-side pepper, so we cannot recover it for you — losing it means rotating the key.

Live keys are prefixed sk_live_. You may see sk_test_ referenced: that prefix is reserved for a sandbox that does not exist yet, and a test key is rejected at authentication today.

Rate limits

The API uses a token bucket per key:

  • Burst capacity: 300 requests
  • Refill: 120 requests per 60 seconds

Creating a webhook subscription costs 5 tokens rather than 1, which discourages subscription spam without affecting normal read traffic.

One deliberate design decision worth knowing: if our cache layer goes down, the limiter fails open rather than closed. Enterprise merchants pay for availability, and we do not take your traffic down to protect our own rate counter.

Every response carries an X-Request-Id header (format req_ plus a 26-character ULID). Quote it if you contact support about a specific call.

Idempotency

Send an Idempotency-Key header on writes. Keys are honoured for 24 hours and may be up to 255 characters. Retrying a create with the same key returns the original result instead of creating a second record — which is what you want when a network error leaves you unsure whether the first attempt landed.

Subscribe to webhooks

  1. Open the Webhooks tab and select Create subscription.
  2. Enter your endpoint URL and choose the events.
  3. Store the signing secret shown at creation.

Verifying the signature

Every delivery is signed HMAC-SHA256 over timestamp.raw_body. To verify:

  1. Read the timestamp and signature from the delivery headers.
  2. Reject anything with a timestamp more than 300 seconds (5 minutes) from your clock.
  3. Recompute the HMAC over timestamp + . + the raw request body — before any JSON parsing or re-serialisation, which would change the bytes.
  4. Compare using a constant-time comparison.

Never skip step 2. Without it, a captured delivery can be replayed against you indefinitely.

Delivery, retries and auto-pause

  • Timeout: 10 seconds per attempt. Return a 2xx quickly and do your work asynchronously — a slow endpoint is treated as a failed one.
  • Payload cap: 256 KB.
  • Retries: 7 retries after the first attempt, at 30s → 2m → 10m → 30m → 2h → 6h → 12h. That spans roughly 24 hours in 8 total attempts.
  • Auto-pause: after 50 consecutive failures the subscription is paused. This protects both sides — an endpoint that has failed 50 times in a row is down, not busy.
  • Concurrency: up to 100 concurrent deliveries per subscription.

Because retries are real, your endpoint must be idempotent. Use the event id to deduplicate.

Rotate a key or secret

Both API keys and webhook signing secrets rotate with a 48-hour grace period: the old value keeps working while you deploy the new one. Rotate, deploy, then let the old value expire — no maintenance window needed.

Verify it is working

  • Make an authenticated request and confirm a 200 with an X-Request-Id header.
  • Check the Deliveries tab after triggering an event — each attempt is listed with its response status.
  • The Usage tab shows request volume against your rate limit.
  • The Docs tab serves the OpenAPI 3.1 document for the current API version.

Troubleshooting

401 on every request

Check the prefix. A sk_test_ key is rejected at authentication; you need a sk_live_ key. Also confirm the key has not been revoked, and that any IP allowlist on the key includes the address you are calling from.

Signature verification fails

Almost always the raw-body problem: the HMAC must be computed over the exact bytes received, before parsing. A framework that parses and re-serialises JSON for you will produce a different string and a different signature.

My subscription paused itself

50 consecutive failures. Fix the endpoint, then re-enable the subscription — deliveries do not resume on their own.

Events stopped arriving but nothing is paused

Check delivery logs for timeouts. An endpoint answering in over 10 seconds is recorded as failed even if it eventually completes the work.

FAQ

How long are logs kept?

Request logs and webhook events are retained for 90 days. Export them if you need longer.

Is there a sandbox?

Not yet. The sk_test_ prefix is reserved for it, but test keys are rejected today.

What happens to my keys if I downgrade from Enterprise?

Access follows your plan, so API access stops. Keys are not destroyed — upgrading restores access without recreating them.