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.

  1. Register a webhook for the UsersChanged event through the Public API.
  2. Store the secret you sent in the registration.
  3. Receive the POST and check its signature header.
  4. Fetch each user listed in Data.users.

You can register for these events:

EventNameValueFires when
SchedulerApproved1A schedule is approved
UsersChanged2One or more users are created or changed
TimeSheetSignedOff3A timesheet is signed off
GapsChanged4One or more gaps are created, updated or deleted
PayrollTriggered5Payroll is triggered
LeaveUpdated6Leave is approved, updated or cancelled
WorkedScheduleUpdated7A schedule with worked shifts is approved, updated or cancelled
UserPayRateChanged8A 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"
}
FieldRules
EventNameUsersChanged (or the integer 2). Any name from the Overview table works the same way.
UrlRequired, 4 to 255 characters, absolute http or https. Loopback hosts are rejected. Use https, because the payload and its signature travel in the request.
SecretRequired, 8 to 128 characters. You choose it; Rotageek does not generate one.

The response is a WebhookResponseModel: Id, EventName, Url, Secret, CreatedOn and UpdatedOn.

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:

  1. Read the raw body bytes before any JSON parsing. Re-serialised JSON produces a different hash.
  2. Compute HMAC-SHA256 over those bytes, using the UTF-8 bytes of the secret as the key.
  3. Hex-encode the result and compare it to the header value after sha256=. Use a constant-time, case-insensitive comparison.
  4. 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

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"]
  }
}
FieldMeaning
TimestampRotageek's clock when it built this delivery, with an offset
UniqueIdNew GUID for each delivery attempt. Use it for replay checks, not for deduplicating events.
EventAlways UsersChanged for this subscription
Data.usersThe 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.

SourceActions that send UsersChangedUsers per message
Web App (admin)Create a user; edit profile, email, Company/Payroll ID, end date, permissions, leave settings or scheduling settings1
Web App (admin)Activate, deactivate or reactivate a user; grant or revoke delegated cover; flag a password reset1
Public APIPOST or PATCH on /api/v{1-4}/users; PUT /api/v1/users/{userId}/userId; add or remove user positions1
User file importEvery user the import created or updatedUp to 500
ESR importEvery user the import created or updatedAll in one message
Rotageek, on your behalfPrimary location recalculated after a position change; the first admin of a new group; a user resync requested through Rotageek support1, 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:

  1. The event does not say what changed. Fetch the user and compare it with your copy.
  2. There is no debounce. An admin who saves profile, then scheduling, then permissions sends three deliveries for the same user.
  3. Deactivation sends UsersChanged, not a separate event. Read IsActive on the fetched user.
  4. Echo loop: users you create or update through the Public API fire UsersChanged back 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>

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.

BehaviourDetail
SuccessAny 2xx, or 410 Gone
FailureAny other status, or no response within 15 seconds
Retries4 retries, 30 seconds apart. After that Rotageek sends no further POST.
DelayUsersChanged deliveries are scheduled 30 seconds after the change. Each change sends its own delivery; nothing is merged.
OrderingNot guaranteed between messages, or across retries
DuplicatesPossible. 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:

  1. The endpoint checks the signature, writes the raw message to a durable queue and returns 200.
  2. 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

  1. Check the signature and return 200 at once. Put the message on your queue and let a separate worker do the fetches.
  2. Key your processing on each Company/Payroll ID in Data.users and re-fetch the user each time.
  3. Run a periodic GET /api/v1/users reconciliation 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.

EventData fieldsFetch the latest data with
SchedulerApprovedlocationUniqueId, from, toGET /api/v1/schedule/locations/{locationUniqueId}?from=&to=
TimeSheetSignedOfflocationId, weekStartDateGET /api/v1/timesheets/locations/{locationId}/{weekStartDate}
GapsUpdatedgapIds, locationId, from, toGET /api/v1/gaps/locations?locationIds={locationId}&from=&to=
PayrollTriggeredstartDate, endDate (includes the whole day), locationIds, triggeredAt—
LeaveUpdatedleaveRequestId, leaveChangeType (Approved, Rejected, Cancelled or Edited), updatedAt; previousExternalId only when a leave import replaced the requestGET /api/v1/leave/requests/{leaveRequestId}
WorkedScheduleUpdatedlocationUniqueId, from, toGET /api/v1/schedule/locations/{locationUniqueId}?from=&to=
UserPayRateChangeduserIds (Company/Payroll IDs)GET /api/v1/users/{userId}/payrates