Gareth Wilson Gareth Wilson

Guide to Salsa Webhooks: Features and Best Practices

Published


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 as Notification.workerPayday, which you might forward to the person concerned.

Salsa webhook features

FeatureDetails
SignatureStandard Webhooks HMAC-SHA256
Signature headerwebhook-signature
BodyJSON
Event routingBody field data.type
ConfigurationAPI only (POST /webhook-endpoints)
Event selectionNone documented
SecretsignatureSecret, whsec_ plus base64; rotation through support
VersioningwebhookVersion per endpoint
RetriesImmediately, 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h
TimeoutNot stated
Suggested tolerance10 minutes

Events and payloads

Salsa's Webhook Events reference documents more than 70 types. The ones most platforms start with:

EventTriggered WhenCommon Use Cases
Employer.createdAn employer is createdStore the employer ID, start onboarding
Employer.updatedAn employer is updatedKeep your records in sync
Employer.onboardingStatusAn employer's onboarding status changesUnlock features when onboarding completes
Worker.createdA worker is createdStore the worker
Worker.updatedA worker is updatedKeep your records in sync
Worker.onboardingStatusA worker's onboarding status changesPrompt the worker to finish onboarding
PayrollRun.awaitingInputA payroll run needs compensation dataSend all compensation data you have for the listed workers
PayrollRun.statusChangedA payroll run's status changesTrack run progress
Notification.workerPaydayThe day a worker is paid (sent at 1pm or 11pm UTC)Notify the worker
Notification.employerPayrollRunConfirmationA payroll run is confirmedNotify the employer
Document.uploadedA document is uploadedFetch the new document
AccountingConfiguration.createdAn accounting configuration is createdSync accounting settings
AccountingConfiguration.updatedAn accounting configuration is updatedSync 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:

FieldDescription
data.typeEvent name, such as Employer.created
data.attributesThe event object, with the IDs of the entities involved
data.attributes.categoryLIFECYCLE or NOTIFICATION

Salsa publishes schemas but no full example bodies, and the body has no event ID. The headers are:

HeaderContents
webhook-idUnique message identifier, the same when an event is resent
webhook-timestampUnix seconds of the delivery attempt
webhook-signatureSpace-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_id}.${webhook_timestamp}.${body}, 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 200 immediately and route the rest by data.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.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.