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.updated or PayrollRun.awaitingInput events?
  • How do I handle the Notification.workerPayday event?
  • 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:

EventTriggered When
Employer.created / Employer.updatedAn employer is created or updated
Employer.onboardingStatusAn employer's onboarding status changes
Worker.created / Worker.updatedA worker is created or updated
Worker.onboardingStatusA worker's onboarding status changes
PayrollRun.awaitingInputA payroll run needs compensation data from you
PayrollRun.statusChangedA payroll run's status changes
Notification.workerPaydayThe day a worker is paid (not sent in the sandbox for Direct Deposit workers)
Notification.employerPayrollRunConfirmationA payroll run is confirmed
Document.uploadedA document is uploaded
AccountingConfiguration.created / .updatedAn 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →