Get a signed message the moment something changes, and handle it safely.
A webhook is Spreadu tapping your software on the shoulder: "a new album is ready". Instead of asking the API every few minutes, your receiver gets a signed HTTPS request as soon as something happens.
Webhooks are perfect for reacting quickly. Pair them with the event feed, which is how you catch up on anything a webhook didn't deliver. Both use the same event envelope.
Lab owners and managers add endpoints in Lab Portal → Lab settings → API, up to five per lab. Your integration can also add its own with an API key.
Give each endpoint:
* for every current and
future type in your lab's enabled modules.Use your own session for changes. Impersonated sessions and Spreadu admins can look at webhook settings and delivery history, but can't save, rotate, enable, remove, test or resend webhooks.
The URL must use port 443, have no credentials or fragment in it, and resolve
entirely to public addresses. IP addresses, localhost and names under
.localhost, .local or .internal are refused. Spreadu runs the same checks
before every attempt, so a DNS change can't turn an approved URL into a private
destination.
Each endpoint has its own signing secret, starting with whsec_. Copy it when
it's shown on creation or rotation and store it with your receiver's secrets.
It's separate from your API key, and Spreadu can't show it again.
After a rotation, Spreadu signs with both the new and the previous secret for 24 hours, so you have time to update your receiver without missing anything.
Before you trust a webhook, check that it really came from Spreadu. Webhooks follow the Standard Webhooks specification, so you don't need to write the crypto yourself. Use an official verifier, such as the JavaScript library, with the endpoint secret, the exact raw request body and these headers:
| Header | Meaning |
|---|---|
webhook-id | Stable ID of the event envelope, for deduplication. |
webhook-timestamp | This attempt's Unix timestamp in seconds. |
webhook-signature | One or more space-separated v1,<base64-signature> values. |
user-agent | Spreadu-Webhooks/1. |
// bun add standardwebhooks
import { Webhook } from "standardwebhooks";
const raw = await request.text();
const secret = process.env.SPREADU_WEBHOOK_SECRET;
if (!secret) throw new Error("Configure the endpoint signing secret.");
const event = new Webhook(secret).verify(
raw,
Object.fromEntries(request.headers),
);
// Persist the verified event under a unique webhook-id before returning 204.If verification fails, return a non-2xx response and don't process the body.
Keep the raw body
The signature covers the exact bytes Spreadu sent. Parsing the JSON and serialising it again can change those bytes, even when the meaning is the same. Verify first, parse second.
How the signature works, if you're curious or verifying by hand: the signed
content is id.timestamp.body, that is the webhook-id, a dot, the timestamp
exactly as received, another dot and the raw body. The signature is
HMAC-SHA256 with the base64-decoded bytes after the secret's whsec_ prefix.
The WordPress guide has a
dependency-free PHP version.
A few rules that keep you safe:
webhook-id.The body is the same event envelope as the feed,
including its sequence and data.
webhook-id.sequence for ordering, not arrival time.GET /events. The feed's
scope, module and type filters can also explain a gap.Return a 2xx status once you've safely recorded the event for processing. Do the slow work, like downloading files, afterwards. Every other status counts as a failure, including 3xx, and redirects are never followed. Live response bodies aren't read; Test mode keeps a short preview for the delivery inspector.
Each attempt gets five seconds to connect and ten seconds in total, including DNS and TLS setup.
A failed event gets up to eight attempts. The wait before each retry:
| Attempt | Wait after the previous failure |
|---|---|
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 6 hours |
| 7 | 12 hours |
| 8 | 24 hours |
Each wait varies by up to 10% either way. A Retry-After header on a 429 or
503 response can stretch the wait up to six hours, but never shortens a wait
that's already longer.
One endpoint receives at most two requests at a time, test pings included. Further deliveries wait for a free slot. Waiting delays them but doesn't use up an attempt. A slow receiver holds at most two of Spreadu's send slots, so your other endpoints keep moving.
Disabling an endpoint cancels its pending deliveries. Removing it also removes its delivery history. When the global API switch or your lab's access is off, nothing is sent, and events from disabled modules are never sent. While your lab's access or a module is off, no events are written at all; see changes that produce no event.
After eight failed attempts a delivery is DEAD. Spreadu never disables the
endpoint because of it, so new events keep going there.
You'll hear about it. In live mode your lab gets an email, at most one per endpoint per UTC day. It goes to the lab's active owners and managers, or to the lab's contact email when there are none, and names the endpoint and its host. No email is sent when the endpoint has been disabled or deleted in the meantime, for test pings or in Test mode.
Each endpoint's Failed deliveries count in API settings (deadDeliveries
in the API) shows how many of its retained deliveries are dead and when the
newest gave up. A resend takes a delivery off the count. A delivery record is
kept for at most 30 days after it finishes, and goes earlier, together with
its event, when that event leaves the feed's 30-day window.
Once your receiver is fixed, recover in one of two ways:
DEAD or a SUCCEEDED
delivery. A resend resets the attempt count and keeps the webhook ID, event
body and occurrence time, with a fresh timestamp and signature. After a busy
outage, older dead deliveries are counted but not listed. A disabled endpoint
refuses resends, so enable it first.GET /events with a key that can read those events.
This always works: every event a counted dead delivery carries is still in
the feed, because the record is removed together with its event.Send a test from the endpoint's controls and your receiver gets a ping. It
uses one attempt and the same signature as every other webhook:
{
"id": "ping_<delivery-id>",
"type": "ping",
"version": 1,
"sequence": "0",
"occurredAt": "<test-created-at-in-UTC>",
"data": {}
}A ping exists only as a webhook. It creates no event in the feed and uses no
sequence number; real events start at "1". Never update your feed cursor from
a ping. Resending a test keeps its ID, body and creation time, with a fresh
timestamp and signature.
Spreadu only delivers to a public HTTPS URL on port 443. Localhost, private networks and IP addresses are refused in Test mode too. A tunnel solves this in a minute.
Run your receiver on 127.0.0.1:3005, then start one of these:
# Cloudflare Tunnel: use the generated https://...trycloudflare.com address
cloudflared tunnel --url http://127.0.0.1:3005
# Or ngrok: use its HTTPS forwarding address
ngrok http 3005Your endpoint URL is https://<tunnel-host>/spreadu. Keep the receiver and the
tunnel running. A temporary tunnel URL can change when you restart it, so update
the endpoint rather than leaving a dead address behind.
In the delivery inspector, compare the three webhook-* headers and the raw
body with what your receiver got, and check that your reverse proxy passes
them through untouched. The response preview shows the first 2 KB; use your
receiver's logs for anything longer. Signing secrets and API keys are never
part of the captured request.
Allow analytics to help us improve these docs? We measure page visits and outgoing links. No session recordings. Privacy policy