Live webinarWhat's new in Sodium: Information Requests, plus Q&A. Thu 19 Nov, 12 noonInformation Requests + Q&A, Thu 19 NovReserve your place

Webhooks

A signed POST to your own URL when a client or task changes, and the API that manages it

OpenAPI Spec

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 work

For 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.

GET/metadata/outbound-webhook-event-types
200 OK
[
  {
    "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 absolute https URL 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 a 400.
  • payloadMode: Full or Thin (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.

POST/tenants/acme/webhooks
{
  "name": "CRM sync",
  "url": "https://crm.example.com/hooks/sodium",
  "eventTypes": ["client.created", "client.updated", "client.archived"],
  "payloadMode": "Full",
  "isEnabled": true
}
201 Created
{
  "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

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.

POST/tenants/acme/webhooks/6f1c2d7e-0b4a-4c8e-9d2f-3a5b7c9e1f20/secret/rotate
200 OK
{
  "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:

HeaderMeaning
webhook-idThe event's unique id. The same on every retry of that event, and the eventId on its deliveries.
webhook-timestampUnix time, in seconds, when this attempt was sent. New on every retry.
webhook-signatureOne or more signatures, separated by spaces, each v1,<base64>.
Content-Typeapplication/json
User-AgentSodium-Webhooks/1.0
POSThttps://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"
  }
}
204 No Content
FieldMeaning
typeThe event type: lowercase words joined by dots, such as client.created.
timestampWhen the change happened, in UTC. Not when this attempt was sent: that is the webhook-timestamp header.
tenantAn 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).
dataThe 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

TypeSent when
client.createdA client is added, by hand, by an import or by the API.
client.updatedA 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.archivedA client's status moves to Inactive from anything else. Moving it back sends only a client.updated.
task.createdA task is created, including tasks generated from a recurring schedule, onboarding tasks and imports.
task.completedA task's status moves to Completed from anything else. Skipped is not completion. A task reopened and completed again sends a second event.
webhook.testOnly 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.

POSThttps://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
    }
  }
}
204 No Content

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.
POSThttps://your-app.example.com/webhooks/sodium
{
  "type": "client.updated",
  "timestamp": "2026-11-16T15:30:00.000Z",
  "tenant": "acme",
  "data": {
    "client": {
      "code": "client_3f9a12"
    }
  }
}
204 No Content
POSThttps://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"
    }
  }
}
204 No Content

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:

  1. Read webhook-id, webhook-timestamp and webhook-signature. Reject the request if any is missing.
  2. Reject it if webhook-timestamp is more than five minutes from your clock, either way. This stops a captured request being replayed.
  3. Build the signed content: ${webhook-id}.${webhook-timestamp}.${body}, using the raw body exactly as it arrived.
  4. Take the secret, remove whsec_, and Base64-decode the rest. Those bytes are the key, not the secret's text.
  5. Compute the HMAC-SHA256 of the signed content with that key, and Base64-encode it.
  6. Accept the request if it equals the signature in any v1 entry of webhook-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:

AttemptSent
1Immediately
25 seconds after attempt 1
35 minutes after attempt 2
430 minutes after attempt 3
52 hours after attempt 4
65 hours after attempt 5
710 hours after attempt 6
814 hours after attempt 7
920 hours after attempt 8
1024 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 answered 410 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 with isEnabled set to false, 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.

GET/tenants/acme/webhooks/deliveries?status=Failed&limit=1
200 OK
{
  "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.

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:

PermissionAllows
ViewAllListing and reading webhooks and deliveries.
CreateCreating a webhook.
UpdateChanging a webhook, rotating its secret, sending a test and retrying a delivery. Holders also get the switched-off notification.
DeleteRemoving 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 tenant is 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.updated is 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.updated and a client.archived, each to the webhooks that subscribe to it.
  • businessDetails can be null on client.created for a client brought in by an import, whose business details are saved just after the client and arrive in a client.updated. Subscribe to client.updated too 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.