Webhooks
A signed POST to your own URL when a client or task changes, and the API that manages it
Overview
A practice (one Sodium account, the tenant in every path) can register OutboundWebhooks: HTTPS URLs it owns, each with a list of event types it wants. When a client is created, updated or archived, or a task is created or completed, Sodium records an event and sends it as a signed HTTP POST to every enabled webhook that subscribes to that type.
Each send of one event to one webhook is an OutboundWebhookDelivery. A delivery is attempted until your receiver answers with a 2xx status, for up to ten attempts over about three days, and every attempt is kept in the practice's delivery log.
Requests follow the Standard Webhooks specification, so a ready-made library can verify them in most languages.
practice "acme"
| a client or task changes in Sodium
v
event type "task.completed", recorded with the change
| one delivery for each webhook that subscribes to the type
v
delivery POST https://your-app.example.com/webhooks/sodium
| signed; retried for about three days until you answer 2xx
v
your receiver verify, store, answer 204, then do the workFor what webhooks do for a practice, rather than how they work, see the Webhooks feature page.
Managing webhooks over the API
Everything the practice's webhook settings screen does is available to an API key with the right permissions (see Permissions and plan), so an integration can register its own webhook. All of these routes answer 409 while webhooks are not switched on in the environment, and 503 when the delivery service behind them is unavailable.
Listing the event types
GET /metadata/outbound-webhook-event-types answers the catalogue of OutboundWebhookEventTypes: each one's type (the name a subscription uses and the receiver sees), a label and a one-line description. It is the same for every practice.
/metadata/outbound-webhook-event-types[
{
"type": "client.created",
"label": "Client created",
"description": "A client was added to the practice."
},
{
"type": "client.updated",
"label": "Client updated",
"description": "A client's details were saved, including when it was archived."
},
{
"type": "client.archived",
"label": "Client archived",
"description": "A client was made inactive."
},
{
"type": "task.created",
"label": "Task created",
"description": "A task was created, including tasks from a recurring schedule."
},
{
"type": "task.completed",
"label": "Task completed",
"description": "A task was marked as completed."
}
]Creating a webhook
POST /tenants/{tenant}/webhooks takes a CreateOutboundWebhookRequest. Every field is required:
name: what the practice calls it, 1 to 100 characters.url: an absolutehttpsURL of at most 2,048 characters, with no user name or password in it.eventTypes: names from the catalogue, or*on its own for every event, including types added later. An empty list, an unknown name, or*mixed with names is refused with a400.payloadMode:FullorThin(see The full record or a reference).isEnabled: whether events are sent to it.
The answer is an OutboundWebhookCreated: the webhook plus its signing secret. This is the only time, besides a rotation, that the secret is returned, so store it straight away. A practice has a limit on how many webhooks it can hold; a create past it answers 409.
/tenants/acme/webhooks{
"name": "CRM sync",
"url": "https://crm.example.com/hooks/sodium",
"eventTypes": ["client.created", "client.updated", "client.archived"],
"payloadMode": "Full",
"isEnabled": true
}{
"id": "6f1c2d7e-0b4a-4c8e-9d2f-3a5b7c9e1f20",
"name": "CRM sync",
"url": "https://crm.example.com/hooks/sodium",
"eventTypes": ["client.created", "client.updated", "client.archived"],
"payloadMode": "Full",
"isEnabled": true,
"disabledReason": null,
"disabledDate": null,
"health": {
"consecutiveFailures": 0,
"failingSince": null,
"coolingDownUntil": null,
"lastSuccessDate": null,
"lastFailureDate": null
},
"currentSecretCreatedDate": "2026-11-16T10:00:00Z",
"previousSecretExpiresDate": null,
"createdDate": "2026-11-16T10:00:00Z",
"updatedDate": null,
"secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}Reading, changing and removing webhooks
- GET /tenants/{tenant}/webhooks lists the practice's webhooks, oldest first, as a page:
data,totalCount,offset,limitandhasMore. Passoffsetandlimit; the limit is 10 by default and at most 50. A practice that has never created a webhook gets an empty page. - GET /tenants/{tenant}/webhooks/{webhookId} reads one. Neither read ever carries the secret.
- PUT /tenants/{tenant}/webhooks/{webhookId} takes an UpdateOutboundWebhookRequest with the same five fields as the create, all required: it replaces the webhook, keeping its secret. Setting
isEnabledtofalsecancels its deliveries still waiting to be sent. Setting it back totrue, or changing theurl, clears its failure history. A changedpayloadModeapplies to deliveries created from then on. - DELETE /tenants/{tenant}/webhooks/{webhookId} removes the webhook with its secrets and its delivery log, and answers
204 No Content.
Each OutboundWebhook carries an OutboundWebhookHealth saying how its receiver has been answering: consecutiveFailures since the last success, failingSince (the first of those failures, null while healthy), coolingDownUntil (set while sends are held back after repeated failures), and lastSuccessDate and lastFailureDate.
Rotating the secret
POST /tenants/{tenant}/webhooks/{webhookId}/secret/rotate issues a new secret and answers it once, in an OutboundWebhookRotatedSecret. The secret it replaces stays valid until previousSecretExpiresDate, a day later, and until then every request is signed with both. Switch your receiver to the new secret any time in that day and nothing is missed.
/tenants/acme/webhooks/6f1c2d7e-0b4a-4c8e-9d2f-3a5b7c9e1f20/secret/rotate{
"secret": "whsec_2b7Qx4LmN9pRs1TuVw3XyZ5aBc7DeF9g",
"previousSecretExpiresDate": "2026-11-17T10:00:00Z"
}Sending a test event
POST /tenants/{tenant}/webhooks/{webhookId}/test sends a webhook.test event to that webhook alone, whatever it subscribes to, and answers the OutboundWebhookDelivery; read the delivery to see how it went. A test is signed like any other event, is attempted once and never retried, and never counts against the webhook's health. It is refused with a 400 while the webhook is switched off.
The event envelope and event types
Every request Sodium sends is a POST with a JSON body, always in the same envelope, and these headers:
| Header | Meaning |
|---|---|
webhook-id | The event's unique id. The same on every retry of that event, and the eventId on its deliveries. |
webhook-timestamp | Unix time, in seconds, when this attempt was sent. New on every retry. |
webhook-signature | One or more signatures, separated by spaces, each v1,<base64>. |
Content-Type | application/json |
User-Agent | Sodium-Webhooks/1.0 |
https://your-app.example.com/webhooks/sodium{
"type": "task.completed",
"timestamp": "2026-11-16T13:08:15.561Z",
"tenant": "acme",
"data": {
"code": "task_8c21d4",
"name": "VAT return Q3",
"status": "Completed",
"dueDate": "2026-11-30",
"clientCode": "client_3f9a12",
"clientName": "Harbour Joinery Ltd",
"assignedUserCode": "jsmith",
"categoryName": "VAT",
"completedDate": "2026-11-16T13:08:15.5233333Z",
"createdDate": "2026-11-02T09:00:00Z"
}
}| Field | Meaning |
|---|---|
type | The event type: lowercase words joined by dots, such as client.created. |
timestamp | When the change happened, in UTC. Not when this attempt was sent: that is the webhook-timestamp header. |
tenant | An identifier for the practice, stable for its webhooks. It is not always the practice's tenant code in API paths (see Things that might surprise you). |
data | The event's content. Its fields depend on the event type and on the webhook's payloadMode. |
A body can be up to 256 KB; most are far smaller. New event types and new fields in data are added over time, so ignore what you do not recognise and still answer 2xx.
The event types
| Type | Sent when |
|---|---|
client.created | A client is added, by hand, by an import or by the API. |
client.updated | A client or its business details are saved, including by a bulk update, an import, the client portal or a sync, and including the save that archives it. |
client.archived | A client's status moves to Inactive from anything else. Moving it back sends only a client.updated. |
task.created | A task is created, including tasks generated from a recurring schedule, onboarding tasks and imports. |
task.completed | A task's status moves to Completed from anything else. Skipped is not completion. A task reopened and completed again sends a second event. |
webhook.test | Only from the test route. Its data is { "message": "This is a test event from Sodium." }. |
The event is recorded in the same database transaction as the change itself. A change that is saved always produces its event; one that fails and is rolled back never does. data describes the record as it was at the moment of the change, not when the request was sent.
Client events
With the full record, data for the three client events holds code, name, type, status, email, telephone, managerCode, createdDate, updatedDate and businessDetails. Enum values are sent by name, as the rest of the API sends them; empty fields are null, not left out.
businessDetails has the same shape as the client's business details in the API: company (number, status, incorporationDate, registeredAddress and sicCodes, the five-digit codes), tradingAs, postalAddress, invoiceAddress, dateOfTrading, natureOfBusiness, utr, vat (registered, number, registrationDate, scheme, reportingPeriod and verified), payeRef, accountsOfficeRef, isCharity and charityNumber. It is null for a client with no business details. The Companies House authentication code is never sent.
https://your-app.example.com/webhooks/sodium{
"type": "client.archived",
"timestamp": "2026-11-16T15:30:00.000Z",
"tenant": "acme",
"data": {
"code": "client_3f9a12",
"name": "Harbour Joinery Ltd",
"type": "PrivateLimitedCompany",
"status": "Inactive",
"email": "accounts@harbourjoinery.example",
"telephone": "01632 960123",
"managerCode": "jsmith",
"createdDate": "2025-04-01T09:00:00Z",
"updatedDate": "2026-11-16T15:30:00Z",
"businessDetails": {
"company": {
"number": "01234567",
"status": "Active",
"incorporationDate": "2015-03-02",
"registeredAddress": "4 Quay Street\nBristol\nBS1 4DJ",
"sicCodes": ["16230", "43320"]
},
"tradingAs": "Harbour Joinery",
"postalAddress": null,
"invoiceAddress": null,
"dateOfTrading": null,
"natureOfBusiness": "Joinery",
"utr": "1234567890",
"vat": {
"registered": true,
"number": "553557881",
"registrationDate": "2016-01-01",
"scheme": "Standard",
"reportingPeriod": "QuarterlyMarJunSepDec",
"verified": true
},
"payeRef": "123/AB45678",
"accountsOfficeRef": "123PF00045678",
"isCharity": false,
"charityNumber": null
}
}
}Task events
With the full record, data for the two task events holds code, name, status, dueDate, clientCode, clientName, assignedUserCode, categoryName, completedDate and createdDate, as in the task.completed example above. A task that belongs to no client has clientCode and clientName of null.
The full record or a reference
Each webhook's payloadMode decides what goes in data. The settings screen shows it as "Send the full record".
Full: the record's fields, as above. The receiver can act without calling back.Thin: only codes. The receiver fetches the record with its own API key, so no client data travels in the webhook.
https://your-app.example.com/webhooks/sodium{
"type": "client.updated",
"timestamp": "2026-11-16T15:30:00.000Z",
"tenant": "acme",
"data": {
"client": {
"code": "client_3f9a12"
}
}
}https://your-app.example.com/webhooks/sodium{
"type": "task.created",
"timestamp": "2026-11-16T15:31:00.000Z",
"tenant": "acme",
"data": {
"task": {
"code": "task_8c21d4",
"clientCode": "client_3f9a12"
}
}
}The envelope is the same in both modes and does not say which one it is: the receiver is expected to know what its webhook asks for. A thin event fetched later shows the record as it is then, which may be newer than the change that sent it.
Verifying signatures
Your endpoint is on the public internet, so anyone can post to it. Verify every request before acting on it. The simplest route is a Standard Webhooks library (standardwebhooks on npm and PyPI, StandardWebhooks on NuGet): give it the secret, with its whsec_ prefix, the raw body and the headers. By hand, the check is:
- Read
webhook-id,webhook-timestampandwebhook-signature. Reject the request if any is missing. - Reject it if
webhook-timestampis more than five minutes from your clock, either way. This stops a captured request being replayed. - Build the signed content:
${webhook-id}.${webhook-timestamp}.${body}, using the raw body exactly as it arrived. - Take the secret, remove
whsec_, and Base64-decode the rest. Those bytes are the key, not the secret's text. - Compute the HMAC-SHA256 of the signed content with that key, and Base64-encode it.
- Accept the request if it equals the signature in any
v1entry ofwebhook-signature, compared in constant time.
Verify the raw body. If your framework parses the JSON first and you verify a re-serialised copy, the spacing or key order may differ and the signature will not match.
Node.js
import crypto from "node:crypto";
const TOLERANCE_SECONDS = 300; // 5 minutes
// rawBody is a Buffer: the request body exactly as it arrived, before any JSON parsing
export function verify(secret, headers, rawBody) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signatureHeader = headers["webhook-signature"];
if (!id || !timestamp || !signatureHeader) return false;
// Reject old (or future) requests, so a captured one cannot be replayed
const sent = Number(timestamp);
if (!Number.isInteger(sent) || Math.abs(Date.now() / 1000 - sent) > TOLERANCE_SECONDS) {
return false;
}
// The key is the Base64-decoded part of the secret after "whsec_"
const key = Buffer.from(secret.slice("whsec_".length), "base64");
const expected = crypto
.createHmac("sha256", key)
.update(id + "." + timestamp + ".")
.update(rawBody)
.digest();
// Accept if any v1 signature matches (there are two during a secret rotation)
return signatureHeader.split(" ").some((entry) => {
const [version, signature] = entry.split(",");
if (version !== "v1" || !signature) return false;
const given = Buffer.from(signature, "base64");
return given.length === expected.length && crypto.timingSafeEqual(given, expected);
});
}C#
using System.Security.Cryptography;
using System.Text;
public static class SodiumWebhookVerifier
{
private const int ToleranceSeconds = 300; // 5 minutes
public static bool Verify(string secret, string id, string timestamp, string signatureHeader, byte[] rawBody)
{
// Reject old (or future) requests, so a captured one cannot be replayed
if (!long.TryParse(timestamp, out var sent)
|| Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - sent) > ToleranceSeconds)
{
return false;
}
// The signed content is "{webhook-id}.{webhook-timestamp}.{raw body}"
var prefix = Encoding.UTF8.GetBytes($"{id}.{timestamp}.");
var signedContent = new byte[prefix.Length + rawBody.Length];
prefix.CopyTo(signedContent, 0);
rawBody.CopyTo(signedContent, prefix.Length);
// The key is the Base64-decoded part of the secret after "whsec_"
var key = Convert.FromBase64String(secret["whsec_".Length..]);
var expected = HMACSHA256.HashData(key, signedContent);
// Accept if any v1 signature matches (there are two during a secret rotation)
foreach (var entry in signatureHeader.Split(' ', StringSplitOptions.RemoveEmptyEntries))
{
var parts = entry.Split(',', 2);
if (parts.Length != 2 || parts[0] != "v1")
{
continue;
}
var given = new byte[expected.Length];
if (Convert.TryFromBase64String(parts[1], given, out var written)
&& written == expected.Length
&& CryptographicOperations.FixedTimeEquals(expected, given))
{
return true;
}
}
return false;
}
}During a rotation webhook-signature carries a signature for each valid secret, newest first. Both samples above accept any of them, as do the Node.js and Python libraries. The C# StandardWebhooks package checks only the first, so with it, switch to the new secret as soon as it is issued.
Retries, ordering and duplicates
Answering
Any 2xx status means received; the response body is ignored. You have 15 seconds for the whole exchange, and a slower answer counts as a failure even if your code finishes later. So verify, store the event or put it on a queue, answer 204, and do the work afterwards. Redirects are not followed: a 3xx is a failure. The first 4,096 characters of your answer are kept in the practice's delivery log, so never put anything secret in it.
The retry schedule
Any other answer, a timeout, a refused connection or a TLS error is a failed attempt, and the delivery is tried again, up to ten attempts in all:
| Attempt | Sent |
|---|---|
| 1 | Immediately |
| 2 | 5 seconds after attempt 1 |
| 3 | 5 minutes after attempt 2 |
| 4 | 30 minutes after attempt 3 |
| 5 | 2 hours after attempt 4 |
| 6 | 5 hours after attempt 5 |
| 7 | 10 hours after attempt 6 |
| 8 | 14 hours after attempt 7 |
| 9 | 20 hours after attempt 8 |
| 10 | 24 hours after attempt 9 |
Each wait is stretched by up to 10% at random, and the whole schedule runs for about three days. Answer 429 or 503 with a Retry-After header and the next attempt waits at least that long, up to an hour. After five failures in a row, or a 429, 502 or 504, sends to the webhook pause for five minutes; the pause uses up none of an event's attempts. After the tenth failure the delivery is Failed, and can be sent again from the delivery log.
Handling duplicates
Delivery is at least once, so the same event can arrive twice, for example when your endpoint did the work but answered too slowly. A retry carries the same webhook-id with a new webhook-timestamp. Keep the ids you have processed for at least a week; when one arrives again, answer 2xx and do nothing.
Not relying on order
Events can arrive out of order: a retry of an older event can land after a newer one. Compare the envelope's timestamp with what you hold and ignore an older event, or treat each event as a prompt and fetch the record's current state through the API.
Switched-off webhooks
A webhook's isEnabled becomes false in three ways, recorded in disabledReason with the time in disabledDate:
Gone: your receiver answered410 Gone. It is switched off at once and nothing is retried. Use it deliberately, when an endpoint is retired.Failing: every attempt has failed for five days since the last success.Manual: someone at the practice, or a PUT withisEnabledset tofalse, switched it off.
For Gone and Failing, the practice's users who can change webhooks get an in-app notification and an email naming the webhook, its URL and the reason. While a webhook is off its waiting deliveries are cancelled, and events that happen in that time are not kept for later. Once your endpoint works again, switch the webhook back on (a PUT with isEnabled set to true, which also clears its failure history) and fetch anything you missed through the API.
The delivery log over the API
GET /tenants/{tenant}/webhooks/deliveries lists OutboundWebhookDeliverys, newest first, paged as the webhook list is (offset, limit 10 by default, at most 50). Optional filters: webhookId, status, eventType, and startDate (inclusive) and endDate (exclusive) as UTC instants.
/tenants/acme/webhooks/deliveries?status=Failed&limit=1{
"data": [
{
"id": "b2e4f6a8-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
"webhookId": "6f1c2d7e-0b4a-4c8e-9d2f-3a5b7c9e1f20",
"eventId": "7d0c1a52-93f4-4f0b-8c0e-5a4f2b6d9e10",
"eventType": "client.updated",
"isTest": false,
"status": "Failed",
"attemptCount": 10,
"nextAttemptDate": null,
"lastStatusCode": 500,
"createdDate": "2026-11-13T09:00:00Z",
"completedDate": "2026-11-16T07:40:00Z"
}
],
"totalCount": 1,
"offset": 0,
"limit": 1,
"hasMore": false
}status is one of Pending, Retrying, Succeeded, Failed or Cancelled. eventId is the webhook-id header your receiver saw, so you can match a log entry to what you stored.
- GET /tenants/{tenant}/webhooks/deliveries/{deliveryId} answers an OutboundWebhookDeliveryDetail: the delivery plus its
payloadMode, the exactpayloadit sends (as a string), and itsattempts, oldest first. Each OutboundWebhookDeliveryAttempt has itsattemptNumber,trigger(Automatic,ManualorTest),outcome(Succeeded,HttpError,Timeout,ConnectionFailedorBlockedTarget),statusCode,responseBody,startedDateanddurationMs. - POST /tenants/{tenant}/webhooks/deliveries/{deliveryId}/retry sends a failed delivery once more, now, and answers the delivery. It answers
409unless the delivery isFailed, its webhook is enabled, and it is not a test.
The display names and colours the settings screen uses for statuses and switch-off reasons are at GET /metadata/outbound-webhook-delivery-statuses and GET /metadata/outbound-webhook-disabled-reasons.
Permissions and plan
Webhooks are part of the Pro package. They have their own permission area in a role, Webhooks (under Practice & Settings), which the API calls OutboundWebhooks:
| Permission | Allows |
|---|---|
ViewAll | Listing and reading webhooks and deliveries. |
Create | Creating a webhook. |
Update | Changing a webhook, rotating its secret, sending a test and retrying a delivery. Holders also get the switched-off notification. |
Delete | Removing a webhook. |
The Admin role holds all four. The built-in Standard and Viewer roles hold none; a custom role can be given any of them. An API key acts with its role's permissions, and is refused when the practice has switched API keys off (see Authentication). The event catalogue and the two lookup lists under /metadata need no permission.
Events carry every client they are about, whatever client-access restrictions apply to individual users: the subscriber is the practice, not a user.
Things that might surprise you
- The envelope's
tenantis not always the tenant code in API paths. It is an identifier issued for the practice's webhooks: stable, so you can key on it, but it can differ from the code you put in/tenants/{tenant}/…. If one receiver serves several practices, give each practice its own URL (a path segment or query value you choose) rather than deriving one code from the other. client.updatedis sent on every save. Even one that changed nothing. Compare with what you hold if you only care about real changes.- Archiving a client sends two events. A
client.updatedand aclient.archived, each to the webhooks that subscribe to it. businessDetailscan benullonclient.createdfor a client brought in by an import, whose business details are saved just after the client and arrive in aclient.updated. Subscribe toclient.updatedtoo if you need them.- A new webhook can take a short while to start receiving. Sodium checks which event types a practice listens for and remembers the answer for about 30 seconds, so a change made straight after creating a webhook may not be sent to it.
- Events that happen while a webhook is off are lost to it. Switching it back on does not replay them; fetch the current state through the API.
- A practice that leaves Pro keeps its webhooks but sends nothing. Events start again if it moves back.
- The secret is shown twice in its life at most. In the create's answer and in a rotation's. Lose it and the only way back is a rotation.