Complete TypeScript and PHP integrations, Bruno and Postman collections, and offline mocks.
Why start from a blank file? These downloads do the whole job already, with the fiddly parts handled: resumable downloads, checksums, retries and signed webhooks. Read them, run them, copy what you like.
Download the TypeScript example or the PHP example. Each one has a local webhook receiver and a client that runs the full cycle.
You need a Full access test key and a working HTTPS tunnel (see Try it on your computer). The examples leave their exports and webhook endpoint in place, so you can inspect them afterwards.
Let the example create its own endpoint
The client manages its webhook endpoint with its API key, and a key can't manage an endpoint added in the portal. If you already added the tunnel URL in the portal, remove that endpoint before running the example.
TypeScript runs on Bun:
unzip spreadu-typescript-example.zip
cd typescript
bun install
export SPREADU_WEBHOOK_SECRET_FILE="$PWD/.spreadu-webhook-secret"
bun run receiver
# In another terminal in this directory, start the tunnel and then:
export SPREADU_KEY="<your-test-key>"
export SPREADU_WEBHOOK_URL="https://<tunnel-host>/spreadu"
bun run cycleThe client saves and rotates the endpoint secret in a shared local file, and
the receiver reads it for every attempt. Export the same
SPREADU_WEBHOOK_SECRET_FILE in both terminals, or keep both in the same
directory. No secret is ever printed. Keep the file out of version control and
delete it when you're done.
It lists exports, follows a cursor, creates and replays a simulator command,
downloads and checks a complete revision, records a receipt twice, confirms
and unlocks an order, requests a correction, downloads revision 2, sees the
withdrawal in the feed and waits for a successful webhook delivery. It stores
nextCursor after every page, also an empty one.
The receivers keep a local journal and deduplicate events. In your production integration, use a durable inbox with a unique event ID and your normal processing queue.
The download code is the part most worth copying. In the TypeScript example it
lives in download.mts and revision-files.mts.
fileIds. Each file's name, size and checksum come from the export detail.
A download-link response that names a file the client didn't ask for, lists
one twice, leaves one out or renames one is refused before anything from
that round is written.Range request. A 416, a 206 that starts at another byte, or a 200 to
a Range request restarts that file from the beginning.Other API calls retry SANDBOX_BUSY and honour Retry-After on rate limits,
within a two-minute retry budget per call. Other failures include the request
ID, so you can look into them before deciding whether to retry.
| Variable | Used by | What it sets |
|---|---|---|
SPREADU_KEY | Client | Your API key. |
SPREADU_WEBHOOK_URL | Client | The public URL of your receiver. |
SPREADU_WEBHOOK_SECRET_FILE | Both | Where the endpoint secret is kept. |
SPREADU_API | Client | The base URL. |
SPREADU_DOWNLOAD_DIR | Client | Where files land. |
SPREADU_DOWNLOAD_IDLE_SECONDS | Client | The idle limit for downloads. |
SPREADU_WEBHOOK_JOURNAL | Receiver | The receiver's journal. |
Each README lists all seven with their defaults.
Prefer clicking to typing? Download the Bruno collection, the Postman collection and the test-mode Postman environment. Their requests come from the published OpenAPI document.
Set up the test environment. Set apiKey to your test key and webhookUrl
to your receiver URL, then select that environment. The collections declare
apiKey only there, as a secret variable. Bruno keeps its value in its own
encrypted store on your computer, not in the collection files.
Start with getMe, then createSandboxExport, then the ordinary export
operations. Successful responses save reference, revision, after and
webhookId where they apply.
Read the feed. Send listEvents first; it reads from the oldest event
still kept. Then listEventsAfterCursor continues from the saved after,
which every response updates, also an empty page.
A few good-to-knows:
confirmExport and setSandboxOrder send the orderNumber variable. It's
empty until you set it, and the server refuses an empty order number.Idempotency-Key and saves it as
idempotencyKey. To replay a command on purpose, copy that key into
replayIdempotencyKey, send the same request again, then clear
replayIdempotencyKey. Any variable scope works in Postman. In Bruno, set it
in the test environment: the script reads other scopes only where your
installed Bruno lets a script read them, and otherwise sends a new key.Keep your key to yourself
Never export or share a Postman environment or collection that holds your key.
For offline unit tests, generate a static mock from the OpenAPI document, for example with Prism. A static mock is great for request and response shapes. Use Test mode to prove transitions, retries, event ordering and signatures.
Allow analytics to help us improve these docs? We measure page visits and outgoing links. No session recordings. Privacy policy