Connect your lab's shop to Spreadu with the WordPress tools you already use.
Running your lab's shop on WordPress or WooCommerce? Good news: a plugin can do everything in this guide with the WordPress HTTP and REST tools you already know. The PHP below was checked against Spreadu's own signer. Sentences about WordPress itself describe general WordPress practice; we haven't tested them on every host.
v1 can't create an album for a shop order, and it can't read your lab's product catalog or prices. Here's the flow that works right now:
The photographer designs the album in Spreadu and submits it to your lab. The export reference exists from that first submission.
The photographer enters the reference at your checkout. Your plugin finds
the export with GET /exports/{reference}.
Once the order is placed, your plugin confirms it with
PUT /exports/{reference}/confirmation, sending the export's
downloadableRevision as revision. The
confirmation body
needs all four fields.
Confirmation succeeds only while that revision is still the current
downloadable one. If the photographer submitted a correction in the meantime,
you get 409 REVISION_NOT_DOWNLOADABLE. Retry with data.downloadableRevision,
or wait for export.available when that is null.
Register a REST route for your endpoint URL and verify the signature against the raw request body, before any JSON decoding. Answer 2xx only after you've stored the event.
If your plugin can't ship the
Standard Webhooks
library, these lines do the same check: the signed content, the whsec_ key,
every v1 signature during a rotation, and a five-minute timestamp window.
function spreadu_verify_webhook(string $raw, array $headers, string $secret): bool
{
$id = $headers['webhook-id'] ?? '';
$timestamp = $headers['webhook-timestamp'] ?? '';
if ($id === '' || preg_match('/^\d+$/', $timestamp) !== 1 || abs(time() - (int) $timestamp) > 300) {
return false;
}
if (!str_starts_with($secret, 'whsec_')) {
return false;
}
$key = base64_decode(substr($secret, 6), true);
if ($key === false || $key === '') {
return false;
}
$expected = base64_encode(hash_hmac('sha256', "$id.$timestamp.$raw", $key, true));
foreach (explode(' ', $headers['webhook-signature'] ?? '') as $candidate) {
[$version, $signature] = array_pad(explode(',', $candidate, 2), 2, '');
if ($version === 'v1' && hash_equals($expected, $signature)) {
return true;
}
}
return false;
}The function needs PHP 8.0 or later and the three webhook-* headers under
lowercase names. As general WordPress practice, WP_REST_Request::get_body()
returns the raw body and get_header() returns one header as a string.
Don't pass get_headers() on
It renames headers (webhook_id) and returns each value as an array, so the
check would always fail. Build the array yourself instead.
$headers = [
'webhook-id' => (string) $request->get_header('webhook-id'),
'webhook-timestamp' => (string) $request->get_header('webhook-timestamp'),
'webhook-signature' => (string) $request->get_header('webhook-signature'),
];
if (!spreadu_verify_webhook($request->get_body(), $headers, SPREADU_WEBHOOK_SECRET)) {
return new WP_Error('invalid_signature', 'Invalid signature', ['status' => 401]);
}Keep the API key and the endpoint secret out of anything a visitor can
download. As general WordPress practice, a constant in wp-config.php, such as
SPREADU_WEBHOOK_SECRET above, or an environment variable set by your host
keeps them out of the database. If you must store them in the options table,
encrypt them with a key that lives outside the database.
Delivery is at least once. Store each event under its webhook-id in a table
with a unique key on that column, and treat a duplicate insert as "already
received".
Use webhooks to react quickly and a scheduled task to catch up with
GET /events?after=<cursor>&wait=0 and GET /exports?updatedSince=<last check>.
As general WordPress practice, WP-Cron runs a due event only when someone
visits the site, and it runs inside a web request to wp-cron.php, with the
time limit of any web request. So never hold a long poll (wait above 0) in a
scheduled event either. A system cron job that calls wp-cron.php makes the
schedule dependable.
Production files are large. Download them outside the webhook request: stream
each file to a directory that isn't publicly served, check its SHA-256, resume
an interrupted file with Range, and record the receipt only when every file
matches.
A WP-Cron event has the same time limit as the webhook request, so a large
revision has to resume across runs, requesting fresh download links each time.
Or run the download from the command line, for example with a system cron job
that runs wp cron event run --due-now through WP-CLI: PHP on the command line
has no time limit by default. The
PHP reference integration shows every step.
Allow analytics to help us improve these docs? We measure page visits and outgoing links. No session recordings. Privacy policy