# SaladCloud Webhooks

[SaladCloud](https://docs.salad.com) 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`).

```javascript
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

```

```python
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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/salad-cloud-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/salad-cloud-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/salad-cloud-webhooks/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](https://github.com/hookdeck/webhook-skills/blob/main/skills/salad-cloud-webhooks/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](https://github.com/hookdeck/webhook-skills/blob/main/skills/salad-cloud-webhooks/references/overview.md) for the payload shape.

## Environment Variables

```bash
# Webhook secret key from the SaladCloud portal: bare base64, no whsec_ prefix
SALAD_CLOUD_WEBHOOK_SECRET=your_base64_secret_here

```

## Local Development

```bash
# 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/salad-cloud-webhooks/references/overview.md) - SaladCloud webhook concepts, event, payload, delivery
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/salad-cloud-webhooks/references/setup.md) - Set the webhook URL per job, get the secret, configure Hookdeck
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/salad-cloud-webhooks/references/verification.md) - Standard Webhooks verification details, header fallback, manual verifier, timestamp window