Agent skill
SaladCloud Webhooks Skill
Receive and verify SaladCloud webhooks (Job Queue API job results, signed with Standard Webhooks). Use when setting up SaladCloud webhook handlers, debugging webhook-signature verification, or handling the queue.job.succeeded event.
Install this skill
npx skills add hookdeck/webhook-skills --skill salad-cloud-webhooks
SaladCloud is a distributed GPU cloud. Its Job Queue API can call a webhook URL with the result of each job. Every delivery is a JSON POST signed with Standard Webhooks headers: webhook-id, webhook-timestamp and webhook-signature. The body is {type, timestamp, data}, where type is the event name (queue.job.succeeded) and data is the job document.
When to Use This Skill
- How do I receive SaladCloud webhooks?
- How do I verify SaladCloud webhook signatures (
webhook-signature, base64 secret)? - How do I handle the
queue.job.succeededevent from the Job Queue API? - Why is my SaladCloud webhook signature verification failing, or rejecting Hookdeck retries?
- What do I paste into a Hookdeck source for my SaladCloud secret?
Verification (core)
Signed content is {webhook-id}.{webhook-timestamp}.{raw body}. SaladCloud signs it with HMAC-SHA256 using the base64-decoded secret, base64-encodes the result, and sends one or more space-separated v1,<signature> entries. Use a Standard Webhooks library (standardwebhooks on npm and PyPI), which compares in constant time. Read the webhook-* headers, and when webhook-id is absent fall back to the svix-* headers (svix-id, svix-timestamp, svix-signature).
const { Webhook } = require('standardwebhooks');
const prefix = req.get('webhook-id') ? 'webhook' : 'svix';
const headers = {
'webhook-id': req.get(`${prefix}-id`),
'webhook-timestamp': req.get(`${prefix}-timestamp`),
'webhook-signature': req.get(`${prefix}-signature`),
};
// rawBody: the raw Buffer/string, never re-serialized JSON
const event = new Webhook(process.env.SALAD_CLOUD_WEBHOOK_SECRET).verify(rawBody, headers);
// throws on a bad signature or a timestamp outside the window; returns the parsed body
from standardwebhooks.webhooks import Webhook, WebhookVerificationError
wh = Webhook(os.environ["SALAD_CLOUD_WEBHOOK_SECRET"]) # bare base64, as shown in the portal
event = wh.verify(raw_body, {"webhook-id": id_, "webhook-timestamp": ts, "webhook-signature": sig})
For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.
The webhook secret key is in the SaladCloud portal. It is a base64 string with no whsec_ prefix. Put it in SALAD_ exactly as shown. The standardwebhooks library strips a whsec_ prefix if there is one and otherwise base64-decodes the whole value, so the bare secret and the whsec_-prefixed form give the same key. Handlers fail closed: with the variable unset they return 500 instead of accepting anything. A missing header or a bad signature returns 400 (401 also works).
Hookdeck needs the secret as whsec_ plus the secret
SaladCloud shows the secret without a prefix, and Hookdeck's configuration alert for this source reads:
SaladCloud shows the secret without a prefix. Paste it as whsec_ followed by the secret, or verification fails.
When you configure the Hookdeck source, enter whsec_. Your own handler, behind or beside Hookdeck, can keep using the bare value.
Hookdeck retries and replays hit the 5-minute window
The Standard Webhooks libraries always enforce a fixed 5-minute timestamp window, and it can't be configured. Hookdeck retries and replays resend the original webhook-timestamp, so the library rejects any retry or replay that happens more than 5 minutes after the original delivery. If you verify behind Hookdeck (or replay old events), use the manual verifier in references/verification.md, where the window can be dropped or widened. The body carries no event id, so deduplicate on webhook-id (or the job id in data.id).
Common Event Types
One event is documented, and the list may not be exhaustive. The name is the top-level type in the JSON body. data.events[].type values (created, started, succeeded) are job lifecycle steps, not webhook events. The examples handle:
| Event | Triggered When |
|---|---|
queue.job.succeeded | A Job Queue job finished successfully. One POST is sent shortly after |
The docs don't cover payloads for failed or cancelled jobs. See references/overview.md for the payload shape.
Environment Variables
# Webhook secret key from the SaladCloud portal: bare base64, no whsec_ prefix
SALAD_CLOUD_WEBHOOK_SECRET=your_base64_secret_here
Local Development
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 salad-cloud --path /webhooks/salad-cloud
Set the Job Queue job's webhook field to the tunnel URL, then submit a job to see the result arrive.
Reference Materials
- references/overview.md - SaladCloud webhook concepts, event, payload, delivery
- references/setup.md - Set the webhook URL per job, get the secret, configure Hookdeck
- references/verification.md - Standard Webhooks verification details, header fallback, manual verifier, timestamp window