Agent skill
Salsa Webhooks Skill
Receive and verify Salsa webhooks (embedded payroll API, signed with Standard Webhooks). Use when setting up Salsa webhook handlers, debugging webhook-signature verification, or handling events like Employer.created, Worker.updated, PayrollRun.awaitingInput, and Notification.workerPayday.
Install this skill
npx skills add hookdeck/webhook-skills --skill salsa-webhooks
Salsa is an embedded payroll API. You create a webhook endpoint through the REST API, and Salsa delivers each event as a JSON POST signed with Standard Webhooks headers: webhook-id, webhook-timestamp and webhook-signature. The body is { "data": { "type": "Employer.created", "attributes": { ... } } }, where data.type is the event name.
When to Use This Skill
- How do I receive Salsa webhooks?
- How do I verify Salsa webhook signatures (
webhook-signature,whsec_secret)? - How do I handle
Employer.created,Worker.updatedorPayrollRun.awaitingInputevents? - How do I handle the
Notification.workerPaydayevent? - Why is my Salsa webhook signature verification failing, or rejecting Hookdeck retries?
Verification (core)
Signed content is {webhook-id}.{webhook-timestamp}.{raw body}. Salsa signs it with HMAC-SHA256 using the base64-decoded secret (the part after whsec_), 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.SALSA_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["SALSA_WEBHOOK_SECRET"]) # "whsec_..."
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 secret is returned as signatureSecret in the Create Webhook Endpoint response (POST /webhook-endpoints). It starts with whsec_. Keep the full value in SALSA_WEBHOOK_SECRET. Salsa's docs print the placeholder some-secret in that response example, so check that the real value starts with whsec_. To rotate the secret, contact Salsa support. Handlers fail closed: with the variable unset they return 500 instead of accepting anything. A missing header or a bad signature returns 400.
The raw body is required: Salsa says not to change the body in any way before verifying.
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 has no event id, so deduplicate on webhook-id, which stays the same when Salsa resends an event.
Common Event Types
More than 70 events are documented, split into LIFECYCLE and NOTIFICATION categories (attributes.category), and the list may not be exhaustive. The name is data.type in the JSON body. The examples handle these:
| Event | Triggered When |
|---|---|
Employer.created / Employer.updated | An employer is created or updated |
Employer.onboardingStatus | An employer's onboarding status changes |
Worker.created / Worker.updated | A worker is created or updated |
Worker.onboardingStatus | A worker's onboarding status changes |
PayrollRun.awaitingInput | A payroll run needs compensation data from you |
PayrollRun.statusChanged | A payroll run's status changes |
Notification.workerPayday | The day a worker is paid (not sent in the sandbox for Direct Deposit workers) |
Notification.employerPayrollRunConfirmation | A payroll run is confirmed |
Document.uploaded | A document is uploaded |
AccountingConfiguration.created / .updated | An accounting configuration changes |
See references/overview.md for more event names and the payload shape.
Environment Variables
# signatureSecret of the webhook endpoint (Standard Webhooks format, starts with whsec_)
SALSA_WEBHOOK_SECRET=whsec_xxxxx
Local Development
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 salsa --path /webhooks/salsa
Create a webhook endpoint whose endpointUrl is the tunnel URL, then create or update an Employer or Worker in the sandbox to see an event arrive.
Reference Materials
- references/overview.md - Salsa webhook concepts, events, payload shape, retries
- references/setup.md - Create and manage an endpoint through the API, get the secret
- references/verification.md - Standard Webhooks verification details, header fallback, manual verifier, timestamp window