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.succeeded event 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_CLOUD_WEBHOOK_SECRET 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_<secret from the portal>. 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:

EventTriggered When
queue.job.succeededA 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →