# Guide to Salsa Webhooks: Features and Best Practices

[Salsa](https://salsa.dev) 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](https://docs.salsa.dev/docs/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

| 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](https://docs.salsa.dev/reference/webhookevent) 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:

```bash
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:

```json
{
  "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](https://docs.salsa.dev/reference/createwebhookendpoint) 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](/docs/cli) URL as the `endpointUrl`:

```bash
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:

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

```javascript
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](/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](/docs/filters) on `data.type` send only the events each service needs, through separate [connections](/docs/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](/docs/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](/webhooks/guides/implement-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](https://hookdeck.com), Salsa's events can be filtered per service and retried beyond Salsa's schedule. [Start free](https://dashboard.hookdeck.com/signup) and register a Salsa source as your sandbox endpoint.