Guide to SaladCloud Webhooks: Features and Best Practices
SaladCloud runs containers on a distributed GPU cloud. For batch work such as inference or transcription, its Job Queue accepts jobs, hands them to your container instances and stores the result. Instead of polling for that result, you can give each job a webhook URL, and SaladCloud posts the finished job to it.
SaladCloud's webhook surface is small: one documented event, a per-job URL and a secret without the usual prefix. This guide explains each piece and the gaps around failed jobs and delivery behaviour.
What are SaladCloud webhooks?
SaladCloud webhooks belong to the Job Queue feature of its Container Engine. There is no account-level subscription. You put a URL in the webhook field of each job you create, and when that job finishes, SaladCloud sends one JSON POST to it shortly afterwards.
Each request carries Standard Webhooks headers, webhook-id, webhook-timestamp and webhook-signature, signed with your webhook secret key from the SaladCloud portal.
SaladCloud webhook features
| Feature | Details |
|---|---|
| Signature | Standard Webhooks HMAC-SHA256 |
| Signature header | webhook-signature |
| Body | JSON |
| Event routing | Body field type |
| Scope | Per job, via the job's webhook field |
| Documented events | queue.job.succeeded |
| Secret | Bare base64 from the portal, no whsec_ prefix |
| Event ID | webhook-id header; data.id is the job |
| Retries, timeout, ordering | Not documented |
| Source IPs | Not published |
Events and payloads
| Event | Triggered When | Common Use Cases |
|---|---|---|
queue.job.succeeded | A Job Queue job finished successfully | Collect the job output, store results, start the next pipeline step |
SaladCloud's page says it documents only the succeeded payload; the type values for failed or cancelled jobs aren't covered. Its example, in which input and output are placeholders:
{
"type": "queue.job.succeeded",
"timestamp": "2026-10-05T21:15:34.4256376Z",
"data": {
"id": "50150edd-e182-47b5-a754-2d2a04d6ee31",
"status": "succeeded",
"input": {},
"output": {},
"events": [
{ "type": "created", "time": "2026-10-05T21:15:32.1180000Z" },
{ "type": "started", "time": "2026-10-05T21:15:33.0120000Z" },
{ "type": "succeeded", "time": "2026-10-05T21:15:34.4010000Z" }
],
"create_time": "2026-10-05T21:15:32.1180000Z",
"update_time": "2026-10-05T21:15:34.4010000Z",
"webhook": "https://callback.example.com/result",
"organization_name": "my-organization",
"project_name": "my-project",
"queue_name": "my-queue"
}
}
data is the job document. input is what you submitted and output is what your container returned. The entries in data.events are job lifecycle steps, not webhook events, and in the Job Queue API's own job document the same field is called action rather than type. Route on the top-level type.
Setting up SaladCloud webhooks
- Find the webhook secret key in the SaladCloud portal and copy it. It is a base64 string without a
whsec_prefix. - Store it as
SALAD_WEBHOOK_SECRETfor your receiver. Both thesvixlibrary and the function below accept it as is. - When you create a job through the Job Queue API, set its
webhookfield to your public HTTPS URL, for examplehttps://example.com/webhooks/salad-cloud. - Submit a test job and check that the result arrives.
Because the URL is set per job, you can point test jobs at a local receiver by using a Hookdeck CLI URL as the webhook:
npx hookdeck-cli listen 3000 salad-cloud --path /webhooks/salad-cloud
With Hookdeck. Create a SaladCloud source and use its URL as the webhook on your jobs. SaladCloud shows the secret without a prefix. Paste it as whsec_ followed by the secret, or verification fails. The source accepts only POST, responds 200 to each delivery, and flags signature failures as failed verification instead of forwarding them.
Securing SaladCloud webhooks
SaladCloud spells out the scheme: base64-decode the secret, compute HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw body} with it, base64-encode the result and compare it with the value after v1,. The function below does that, decoding the secret whether or not it has a whsec_ prefix:
const crypto = require('node:crypto');
function decodeBase64(value) {
if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
const bytes = Buffer.from(value, 'base64');
return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
? bytes : null;
}
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const prefix = headers['webhook-id'] !== undefined ? 'webhook' : 'svix';
const id = headers[`${prefix}-id`];
const timestamp = headers[`${prefix}-timestamp`];
const signature = headers[`${prefix}-signature`];
if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
!/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
const key = decodeBase64(secret.replace(/^whsec_/, ''));
if (!key) return false;
const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
const received = decodeBase64(candidate);
if (!received) return false;
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
A receiver that stores each job's output and logs anything it doesn't recognise, such as the undocumented failure types:
const express = require('express');
// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
try {
const value = JSON.parse(rawBody.toString('utf8'));
return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
} catch {
return null;
}
}
const app = express();
app.post('/webhooks/salad-cloud', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.SALAD_WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
const payload = parseJsonObject(req.body);
if (!payload) return res.sendStatus(400); // signed, but not a JSON object
const { type, data } = payload;
if (typeof type !== 'string') return res.sendStatus(400);
try {
if (type === 'queue.job.succeeded') {
if (!data || typeof data !== 'object') return res.sendStatus(400);
await results.save(data.id, data.queue_name, data.output);
} else {
console.warn('Unhandled SaladCloud event', type, data?.id, data?.status);
}
} catch {
return res.sendStatus(503); // not processed, so don't acknowledge
}
return res.sendStatus(200);
});
results stands for your own storage; saving by data.id makes a repeated delivery harmless.
The svix library in SaladCloud's examples rejects any webhook-timestamp more than five minutes from your clock. Hookdeck doesn't check timestamp age, and its retries and replays keep SaladCloud's original timestamp, so a service behind Hookdeck that verifies with the library would reject them. Skip the age check there, as this function does.
Make SaladCloud webhooks production-ready. Hookdeck Event Gateway stores every job result as it arrives, so a receiver outage doesn't cost you GPU time spent on jobs whose output never landed.
SaladCloud webhook limitations and pain points
Only success is documented
The Problem: You don't know what arrives, if anything, when a job fails or is cancelled.
Why It Happens: SaladCloud documents only queue.job.succeeded and says other type values aren't covered.
Workarounds:
- Log and keep any unknown
typerather than discarding it. - Poll the Job Queue API for jobs that haven't reported back within your expected run time.
How Hookdeck Can Help: Hookdeck records every request, so the first failure event that arrives shows its exact shape. A filter can then route it separately.
Undocumented delivery behaviour
The Problem: If your receiver is down, you can't tell whether SaladCloud will try again.
Why It Happens: The documentation describes one POST per job and says nothing about retries, timeouts or ordering.
Workarounds:
- Treat the webhook as a notification and reconcile against the Job Queue API for completeness.
How Hookdeck Can Help: Hookdeck acknowledges straight away and retries delivery to your service, so the single SaladCloud attempt only needs to reach Hookdeck.
The secret has no prefix
The Problem: Hookdeck or another Standard Webhooks tool fails to verify valid requests.
Why It Happens: The portal shows bare base64. Some tools only base64-decode a secret that starts with whsec_ and use anything else as plain text.
Workarounds:
- Pass the bare secret to the
svixlibrary, andwhsec_plus the secret to Hookdeck.
How Hookdeck Can Help: Verifying on the source keeps the secret out of the service that processes results.
A URL per job
The Problem: Changing the receiver URL means changing the code that submits jobs, and jobs already queued still use the old URL.
Why It Happens: The webhook URL is stored on each job.
Workarounds:
- Read the URL from configuration when submitting jobs, and keep old URLs working until queued jobs drain.
How Hookdeck Can Help: Put a stable Hookdeck source URL on every job and change destinations behind it without touching job submission.
Best practices
Use the job ID for results
data.id identifies the job across the webhook and the Job Queue API. Store output against it, so a duplicate delivery overwrites rather than duplicates. The webhook-id header also works as a key; see our idempotency guide.
Size your receiver for the output
output is whatever your container returned, so its size depends on your application. Make sure your body size limits allow for it, and store the output before any further processing.
Keep the body raw
SaladCloud's own Express example uses express.raw({ type: 'application/json' }). Use the raw bytes for verification and parse afterwards.
Fail closed
If SALAD_WEBHOOK_SECRET isn't set, return an error rather than accepting unverified results.
Conclusion
SaladCloud's Job Queue webhooks save you from polling for results: set a URL on each job and SaladCloud posts the finished job there. Verify with the bare base64 secret (or whsec_ plus it for Hookdeck), store output by job ID, and plan for failure outcomes and retry behaviour the documentation doesn't yet describe.
Hookdeck Event Gateway gives each job's result a stable URL and a retry policy you control. Sign up and set a SaladCloud source URL as your jobs' webhook.