Gareth Wilson Gareth Wilson

Guide to SaladCloud Webhooks: Features and Best Practices

Published


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

FeatureDetails
SignatureStandard Webhooks HMAC-SHA256
Signature headerwebhook-signature
BodyJSON
Event routingBody field type
ScopePer job, via the job's webhook field
Documented eventsqueue.job.succeeded
SecretBare base64 from the portal, no whsec_ prefix
Event IDwebhook-id header; data.id is the job
Retries, timeout, orderingNot documented
Source IPsNot published

Events and payloads

EventTriggered WhenCommon Use Cases
queue.job.succeededA Job Queue job finished successfullyCollect 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

  1. Find the webhook secret key in the SaladCloud portal and copy it. It is a base64 string without a whsec_ prefix.
  2. Store it as SALAD_WEBHOOK_SECRET for your receiver. Both the svix library and the function below accept it as is.
  3. When you create a job through the Job Queue API, set its webhook field to your public HTTPS URL, for example https://example.com/webhooks/salad-cloud.
  4. 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 type rather 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 svix library, and whsec_ 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.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.