Guide to Salsa Webhooks: Features and Best Practices
Salsa provides an embedded payroll API, so software platforms can run payroll for their own customers. Payroll is a sequence of steps that happen over days: an employer onboards, workers are added, a payroll run asks for compensation data, money moves, documents appear. Salsa's webhooks report each of those steps so your platform can react without polling.
Read on for Salsa's event categories, the API-only endpoint setup, the Standard Webhooks signature, and the retry schedule.
What are Salsa webhooks?
Salsa webhooks go to webhook endpoints that you create through the REST API, as described in Consuming webhooks. An endpoint receives the events Salsa sends for your account; the docs describe no way to pick individual events. Each delivery is a JSON POST signed with Standard Webhooks headers.
Events fall into two categories, given in data.attributes.category:
LIFECYCLE: changes to employers, workers, payroll runs, payments and documents.NOTIFICATION: reminders and notices, such asNotification.workerPayday, which you might forward to the person concerned.
Salsa webhook features
| Feature | Details |
|---|---|
| Signature | Standard Webhooks HMAC-SHA256 |
| Signature header | webhook-signature |
| Body | JSON |
| Event routing | Body field data.type |
| Configuration | API only (POST /webhook-endpoints) |
| Event selection | None documented |
| Secret | signatureSecret, whsec_ plus base64; rotation through support |
| Versioning | webhookVersion per endpoint |
| Retries | Immediately, 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h |
| Timeout | Not stated |
| Suggested tolerance | 10 minutes |
Events and payloads
Salsa's Webhook Events reference documents more than 70 types. The ones most platforms start with:
| Event | Triggered When | Common Use Cases |
|---|---|---|
Employer.created | An employer is created | Store the employer ID, start onboarding |
Employer.updated | An employer is updated | Keep your records in sync |
Employer.onboardingStatus | An employer's onboarding status changes | Unlock features when onboarding completes |
Worker.created | A worker is created | Store the worker |
Worker.updated | A worker is updated | Keep your records in sync |
Worker.onboardingStatus | A worker's onboarding status changes | Prompt the worker to finish onboarding |
PayrollRun.awaitingInput | A payroll run needs compensation data | Send all compensation data you have for the listed workers |
PayrollRun.statusChanged | A payroll run's status changes | Track run progress |
Notification.workerPayday | The day a worker is paid (sent at 1pm or 11pm UTC) | Notify the worker |
Notification.employerPayrollRunConfirmation | A payroll run is confirmed | Notify the employer |
Document.uploaded | A document is uploaded | Fetch the new document |
AccountingConfiguration.created | An accounting configuration is created | Sync accounting settings |
AccountingConfiguration.updated | An accounting configuration is updated | Sync accounting settings |
The rest, grouped:
- Employer:
Employer.deleted,Employer.awaitingRiskInsights,Employer.Address.created,Employer.Address.updated,Employer.Address.deleted,Employer.AccountStanding.statusChanged,Employer.AccountStanding.requirementsChanged,Employer.PayWorkersReadiness.statusChanged,Employer.PayWorkersReadiness.requirementsChanged,Employer.TaxesSetup.updated,Employer.PayType.created,Employer.PayType.updated,Employer.PayType.deleted,Employer.TimeOffType.created,Employer.WorkerPayGroup.created - Payroll history:
Employer.PayrollHistory.required,Employer.PayrollHistory.provided,Employer.PayrollHistory.importCompleted,Employer.PayrollHistory.statusChanged - Bank accounts and signatories:
EmployerBankAccount.created,EmployerBankAccount.updated,EmployerBankAccount.deleted,EmployerBankAccount.Verification.statusChanged,EmployerSignatory.created,WorkerBankAccount.created,WorkerBankAccount.updated,WorkerBankAccount.deleted - Workers:
Worker.deleted,Worker.PaymentsReadiness.statusChanged,Worker.TaxesSetup.updated,Worker.Termination.statusChanged,WorkerContract.created,WorkerPayDistribution.updated,WorkerPaymentAdjustment.created,WorkerPersonalInformation.created,WorkerPersonalInformation.updated - Payroll runs and payments:
PayrollRun.deleted,PayrollRun.EmployerFunding.statusChanged,PayrollRun.WorkerDisbursement.MoneyMovementTransaction.statusChanged,Notification.Payment.employerFundingFailed,Notification.Payment.workerDisbursementFailed,Notification.Payment.workerDisbursementScheduled - Other notifications:
Notification.employerPaydayReminder,Notification.employerPayrollOperation,Notification.employerPayrollHistoryRequired,Notification.Employer.taxRateUpdatedFromAgency - Documents:
Document.deleted
The reference may not be exhaustive, so acknowledge unknown types.
Every delivery uses one envelope, defined in each event's reference schema:
| Field | Description |
|---|---|
data.type | Event name, such as Employer.created |
data.attributes | The event object, with the IDs of the entities involved |
data.attributes.category | LIFECYCLE or NOTIFICATION |
Salsa publishes schemas but no full example bodies, and the body has no event ID. The headers are:
| Header | Contents |
|---|---|
webhook-id | Unique message identifier, the same when an event is resent |
webhook-timestamp | Unix seconds of the delivery attempt |
webhook-signature | Space-separated v1,<base64> signatures |
Setting up Salsa webhooks
Create an endpoint with your API token. This example uses the sandbox:
curl --request POST \
--url https://api.sandbox.salsa.dev/api/rest/v1/webhook-endpoints \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'authorization: Bearer [your-auth-token]' \
--data '{
"description": "This is my webhook endpoint that will receive events",
"endpointUrl": "https://my-webhook-url.com/path"
}'
The response:
{
"data": {
"id": "prtnrendpt_8ae05235-927e-449f-a40a-9611bc4794ee",
"description": "This is my webhook endpoint that will receive events",
"endpointUrl": "https://my-webhook-url.com/path",
"status": "ENABLED",
"webhookVersion": "2023-01-01",
"signatureSecret": "some-secret"
}
}
signatureSecret is the signing secret. The documentation prints the placeholder some-secret; a real one is whsec_ followed by base64. Store the full value as SALSA_WEBHOOK_SECRET. The endpoint is ENABLED straight away.
To change endpointUrl, description, status or webhookVersion, send PUT /webhook-endpoints/{webhookEndpointId}. Disabling an endpoint stops all delivery attempts to it. The Create Webhook Endpoint reference has the exact request shapes.
The sandbox behaves like production, with one exception: it doesn't send Notification.workerPayday for Direct Deposit workers. To receive sandbox events on your machine, register a Hookdeck CLI URL as the endpointUrl:
npx hookdeck-cli listen 3000 salsa --path /webhooks/salsa
With Hookdeck. Create a Salsa source, pass its URL as endpointUrl, and paste signatureSecret into it. Salsa gets a 200 for every POST; a delivery with a bad signature is recorded as failed verification and not sent on. The source does not accept other methods.
Securing Salsa webhooks
Salsa's guide describes the Standard Webhooks construction: the signed content is ${webhook_, the key is the base64-decoded part of the secret after whsec_, and webhook-signature is a space-separated list of versioned signatures. Salsa says not to change the body in any way before verifying:
const crypto = require('node:crypto');
function decodeBase64(value) {
if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
const bytes = Buffer.from(value, 'base64');
return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
? bytes : null;
}
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const prefix = headers['webhook-id'] !== undefined ? 'webhook' : 'svix';
const id = headers[`${prefix}-id`];
const timestamp = headers[`${prefix}-timestamp`];
const signature = headers[`${prefix}-signature`];
if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
!/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
const key = decodeBase64(secret.replace(/^whsec_/, ''));
if (!key) return false;
const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
const received = decodeBase64(candidate);
if (!received) return false;
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
A handler for the payroll-run and payday events:
const express = require('express');
// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
try {
const value = JSON.parse(rawBody.toString('utf8'));
return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
} catch {
return null;
}
}
const app = express();
app.post('/webhooks/salsa', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.SALSA_WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
const payload = parseJsonObject(req.body);
if (!payload) return res.sendStatus(400); // signed, but not a JSON object
const { data } = payload;
if (!data || typeof data !== 'object' || typeof data.type !== 'string') return res.sendStatus(400);
const message_id = req.headers['webhook-id'];
try {
switch (data.type) {
case 'PayrollRun.awaitingInput':
await payroll.submitCompensation(message_id, data.attributes);
break;
case 'Notification.workerPayday':
await notifications.sendPayday(message_id, data.attributes);
break;
case 'Employer.onboardingStatus':
case 'Worker.onboardingStatus':
await onboarding.sync(message_id, data.type, data.attributes);
break;
default:
break;
}
} catch {
return res.sendStatus(503); // not processed, so don't acknowledge
}
return res.sendStatus(200);
});
payroll, notifications and onboarding are your own services. Queue the compensation submission rather than calling Salsa's API inline if it might be slow.
Salsa suggests receivers reject timestamps more than ten minutes from their clock. That suits direct delivery, since each Salsa attempt has its own timestamp. The Standard Webhooks and Svix libraries are stricter, at five minutes. Neither works behind Hookdeck, which applies no tolerance and replays Salsa's original webhook-timestamp on its retries; verify without an age check there.
Make Salsa webhooks production-ready. Hookdeck Event Gateway gives Salsa's single endpoint per-event routing, and keeps payroll events safe if your service is down for longer than Salsa's retries.
Salsa webhook limitations and pain points
No event selection
The Problem: Every endpoint receives every event type, including dozens your platform may not use.
Why It Happens: Salsa documents no per-endpoint event filter.
Workarounds:
- Acknowledge unwanted types with
200immediately and route the rest bydata.type.
How Hookdeck Can Help: Filters on data.type send only the events each service needs, through separate connections.
Rotation goes through support
The Problem: A leaked secret can't be replaced on the spot.
Why It Happens: signatureSecret is returned only on create, and Salsa's docs say to contact support to rotate it.
Workarounds:
- Store the secret in a secret manager at creation and limit who can read it.
- Ask support how the switch-over works, because the docs don't say whether old and new secrets overlap.
How Hookdeck Can Help: Verifying on the Hookdeck source means only one system holds the secret.
No examples, and one ambiguous name
The Problem: Fixtures have to be built from schemas, and one event may not arrive under the name you expect.
Why It Happens: Salsa publishes per-event schemas but no complete bodies. The reference lists WorkerPayDistribution.updated but its description says it triggers WorkerPaymentDistribution.updated.
Workarounds:
- Capture sandbox deliveries for fixtures, and match both spellings until you've seen a real one.
How Hookdeck Can Help: Hookdeck stores each sandbox delivery, so the actual data.type strings are easy to check.
Retries end after about 28 hours
The Problem: A payroll notification that fails for more than a day is lost.
Why It Happens: Salsa retries on a fixed schedule ending with two 10-hour waits, roughly 27.6 hours after the first attempt.
Workarounds:
- After an outage, check payroll run and worker state through the API.
How Hookdeck Can Help: Hookdeck takes delivery from Salsa straight away and retries your service for as long as you set.
Best practices
Respond to PayrollRun.awaitingInput promptly
Salsa uses this event to ask for compensation data for the listed workers. Send everything you have, and alert someone if your system can't.
Deduplicate on webhook-id
The body has no event ID, and webhook-id is kept when Salsa resends. Our guide to webhook idempotency covers durable storage.
Separate notifications from lifecycle events
NOTIFICATION events are prompts to message people; LIFECYCLE events change your data. Routing them to different handlers keeps a slow email service from delaying record updates.
Pin the webhook version
Endpoints carry a webhookVersion. Record which one each endpoint uses and change it deliberately with PUT.
Conclusion
Salsa's webhooks follow every stage of embedded payroll, from onboarding to payday. Create the endpoint through the API and save signatureSecret, route on data.type yourself, deduplicate on webhook-id, and answer PayrollRun.awaitingInput quickly.
Behind Hookdeck Event Gateway, Salsa's events can be filtered per service and retried beyond Salsa's schedule. Start free and register a Salsa source as your sandbox endpoint.