Webhooks Integration Guide
How to register for Rotageek webhooks, check their signatures and process deliveries, with the UsersChanged event as the worked example.
Overview
Rotageek webhooks POST a small JSON message to your system when something changes in your group. Each message names what changed, so you fetch the full record from the Public API.
This guide covers the UsersChanged event, which tells you that one or more users were created or changed. The registration, signing and delivery rules apply to every event.
- Register a webhook for the
UsersChangedevent through the Public API. - Store the secret you sent in the registration.
- Receive the POST and check its
signatureheader. - Fetch each user listed in
Data.users.
You can register for these events:
EventName | Value | Fires when |
|---|---|---|
SchedulerApproved | 1 | A schedule is approved |
UsersChanged | 2 | One or more users are created or changed |
TimeSheetSignedOff | 3 | A timesheet is signed off |
GapsChanged | 4 | One or more gaps are created, updated or deleted |
PayrollTriggered | 5 | Payroll is triggered |
LeaveUpdated | 6 | Leave is approved, updated or cancelled |
WorkedScheduleUpdated | 7 | A schedule with worked shifts is approved, updated or cancelled |
UserPayRateChanged | 8 | A user's pay rate is created, updated or deleted |
The Event field in a delivery uses the internal name. For value 4 that name is GapsUpdated, not GapsChanged.
Registering a webhook
To register, send POST /api/v1/webhooks to the Public API with a JWT bearer token from POST /api/v1/auth. Only an Admin can register webhooks.
POST /api/v1/webhooks
Authorization: Bearer <access token>
Content-Type: application/json
{
"EventName": "UsersChanged",
"Url": "https://receiver.example.com/rotageek/users",
"Secret": "a-long-random-string-you-generate"
}
| Field | Rules |
|---|---|
EventName | UsersChanged (or the integer 2). Any name from the Overview table works the same way. |
Url | Required, 4 to 255 characters, absolute http or https. Loopback hosts are rejected. Use https, because the payload and its signature travel in the request. |
Secret | Required, 8 to 128 characters. You choose it; Rotageek does not generate one. |
The response is a WebhookResponseModel: Id, EventName, Url, Secret, CreatedOn and UpdatedOn.
- One event per registration: to receive several events, register once per event. You can use the same URL for different events.
- Duplicate URLs: you cannot register the same URL twice for the same event. The check ignores
www.and case, and returns409 ConflictingValues. - Several receivers: you can register several different URLs for
UsersChanged. Each one receives its own POST. - Start-up delay: Rotageek caches your group's registrations for 10 minutes. A new, changed or deleted webhook can take up to 10 minutes to take effect.
- Other endpoints:
GET /api/v1/webhooks,GET /api/v1/webhooks/{id},PUT /api/v1/webhooks/{id}(URL only) andDELETE /api/v1/webhooks/{id}.
Signing secret
Every POST carries a signature header: sha256= followed by the HMAC-SHA256 of the raw request body, keyed with the secret. The hex is uppercase with no separators.
signature: sha256=9F86D081884C7D659A2FEAA0C55AD015A3BF4F1B2B0B822CD15D6C15B0F00A08
To check a delivery:
- Read the raw body bytes before any JSON parsing. Re-serialised JSON produces a different hash.
- Compute HMAC-SHA256 over those bytes, using the UTF-8 bytes of the secret as the key.
- Hex-encode the result and compare it to the header value after
sha256=. Use a constant-time, case-insensitive comparison. - Reject the request with a 401 if the values differ.
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
var expected = Convert.ToHexString(hmac.ComputeHash(rawBody)); // uppercase
var received = signatureHeader["sha256=".Length..];
var valid = CryptographicOperations.FixedTimeEquals(
Encoding.ASCII.GetBytes(expected),
Encoding.ASCII.GetBytes(received.ToUpperInvariant()));
How Rotageek stores the secret
- The Public API decrypts it on read.
GET /api/v1/webhooksandGET /api/v1/webhooks/{id}return the secret in plain text to any Admin in your group. PUTchanges only the URL. To rotate a secret, create a new webhook with the new secret and delete the old one. Accept both secrets during the 10-minute cache window.- The signature covers the body only. There is no signed timestamp, so replay protection is up to you. Track
UniqueIdvalues you have already seen and reject repeats.
Payload
Rotageek sends a POST with Content-Type: application/json and a 15-second timeout. Every event uses the same envelope; only Data changes. For UsersChanged, Data holds a list of Company/Payroll IDs:
{
"Timestamp": "2026-10-26T09:15:02.1234567+00:00",
"UniqueId": "3f2b8c1e-6a4d-4f0e-9b7a-1c2d3e4f5a6b",
"Event": "UsersChanged",
"Data": {
"users": ["EMP-123", "EMP-456"]
}
}
| Field | Meaning |
|---|---|
Timestamp | Rotageek's clock when it built this delivery, with an offset |
UniqueId | New GUID for each delivery attempt. Use it for replay checks, not for deduplicating events. |
Event | Always UsersChanged for this subscription |
Data.users | The changed users' Company/Payroll IDs (strings), not internal integer IDs. |
One message can name one user or many. A single admin edit names one user. A user import names up to 500 users per message.
The envelope keys are PascalCase and the Data keys are camelCase, because the two parts go through different serialisers. Parse keys case-insensitively. The payload says nothing about what changed on each user, so fetch each user for that.
When UsersChanged fires
UsersChanged fires when a user record or its core settings are saved, from the Web App, the Public API or an import. Rotageek sends each delivery 30 seconds after the change, with no merging.
| Source | Actions that send UsersChanged | Users per message |
|---|---|---|
| Web App (admin) | Create a user; edit profile, email, Company/Payroll ID, end date, permissions, leave settings or scheduling settings | 1 |
| Web App (admin) | Activate, deactivate or reactivate a user; grant or revoke delegated cover; flag a password reset | 1 |
| Public API | POST or PATCH on /api/v{1-4}/users; PUT /api/v1/users/{userId}/userId; add or remove user positions | 1 |
| User file import | Every user the import created or updated | Up to 500 |
| ESR import | Every user the import created or updated | All in one message |
| Rotageek, on your behalf | Primary location recalculated after a position change; the first admin of a new group; a user resync requested through Rotageek support | 1, or up to 100 for a resync |
Nothing is sent for these Public API writes: skills, pay rates, leave allowances, visas, contract types and term times. Pay rates have their own event, UserPayRateChanged.
Nuances you must handle:
- The event does not say what changed. Fetch the user and compare it with your copy.
- There is no debounce. An admin who saves profile, then scheduling, then permissions sends three deliveries for the same user.
- Deactivation sends
UsersChanged, not a separate event. ReadIsActiveon the fetched user. - Echo loop: users you create or update through the Public API fire
UsersChangedback to you. Compare the fetched record with what you wrote and skip it when nothing changed.
Fetching the users
Pass each value in Data.users straight to GET /api/v1/users/{userId}. The endpoint looks the user up by Company/Payroll ID within your group. Use the same Admin token you used to register the webhook.
GET /api/v1/users/EMP-123
Authorization: Bearer <access token>
- One call per user. A message from an import can list 500 users. Queue the fetches and pace them.
- Deactivated users still return. The lookup does not filter on active state, so read
IsActiveon every fetch. - The fetched record is the source of truth. Several deliveries can arrive for one user. Each fetch returns the current state, so process them in any order.
- Other versions:
GET /api/v3/users/{userId}andGET /api/v4/users/{userId}take the same Company/Payroll ID. Use the version you already call.
Delivery behaviour
Rotageek tries each delivery up to 5 times over about 2 minutes, then gives up. You must respond quickly and handle repeats and gaps.
| Behaviour | Detail |
|---|---|
| Success | Any 2xx, or 410 Gone |
| Failure | Any other status, or no response within 15 seconds |
| Retries | 4 retries, 30 seconds apart. After that Rotageek sends no further POST. |
| Delay | UsersChanged deliveries are scheduled 30 seconds after the change. Each change sends its own delivery; nothing is merged. |
| Ordering | Not guaranteed between messages, or across retries |
| Duplicates | Possible. A retry after a slow 2xx sends the same event again with a new UniqueId and Timestamp. |
Decouple receipt from processing
Keep your webhook endpoint thin, and ideally put a queue between it and the work:
- The endpoint checks the signature, writes the raw message to a durable queue and returns
200. - A separate worker reads from the queue, fetches each user and applies the change in your system.
This keeps every response well inside the 15-second timeout, even when an import lists 500 users in one message. A slow or unavailable downstream system then delays your own processing instead of failing deliveries. Your queue can also keep retrying after Rotageek stops at 5 attempts.
Any durable queue works, such as Azure Service Bus, Amazon SQS or RabbitMQ. A database table that a background job polls also works at lower volumes.
To receive deliveries reliably
- Check the signature and return
200at once. Put the message on your queue and let a separate worker do the fetches. - Key your processing on each Company/Payroll ID in
Data.usersand re-fetch the user each time. - Run a periodic
GET /api/v1/usersreconciliation to catch events lost after 5 failed attempts.
Other events
Every other event uses the same registration, signature, envelope and delivery rules. Only Data differs, and its keys are camelCase.
Event | Data fields | Fetch the latest data with |
|---|---|---|
SchedulerApproved | locationUniqueId, from, to | GET /api/v1/schedule/locations/{locationUniqueId}?from=&to= |
TimeSheetSignedOff | locationId, weekStartDate | GET /api/v1/timesheets/locations/{locationId}/{weekStartDate} |
GapsUpdated | gapIds, locationId, from, to | GET /api/v1/gaps/locations?locationIds={locationId}&from=&to= |
PayrollTriggered | startDate, endDate (includes the whole day), locationIds, triggeredAt | — |
LeaveUpdated | leaveRequestId, leaveChangeType (Approved, Rejected, Cancelled or Edited), updatedAt; previousExternalId only when a leave import replaced the request | GET /api/v1/leave/requests/{leaveRequestId} |
WorkedScheduleUpdated | locationUniqueId, from, to | GET /api/v1/schedule/locations/{locationUniqueId}?from=&to= |
UserPayRateChanged | userIds (Company/Payroll IDs) | GET /api/v1/users/{userId}/payrates |