Skip to main content

Webhooks

Webhooks notify your integration when requisitions, assignments, timesheets and related records change. Each event contains a stable event ID, event type, creation time and affected record ID. Use the corresponding API detail endpoint when you need the current record.

A webhook subscription and an API key are separate credentials. Subscribing to an event does not grant permission to fetch the referenced record; follow-up API requests still require the appropriate scope and company or agency access.

Configure a subscription​

Webhooks are configured in the Requidex application. Open the relevant hiring company or agency, select Integrations, and then open the Webhooks tab. Company webhooks are available to users who can manage that company's integrations. For agencies, agency webhook access must be enabled before the Integrations section is available to agency administrators.

To create a webhook, choose New Webhook, enter its name and receiving endpoint URL, select the event types, and save it. You can also add a description or custom headers and choose whether the webhook is active immediately. Requidex generates the signing secret automatically; store it securely and use it to verify delivery signatures.

Each webhook belongs to exactly one hiring company or agency. From the Webhooks tab you can edit or activate/deactivate it, change its subscribed events, send a test event, inspect or export delivery logs, reveal the signing secret, or delete the webhook. Agency webhook delivery remains restricted to requisitions and workers relevant to that agency.

Subscription availability​

CategoryCompany webhooksAgency webhooks
RequisitionsAll except Requisition receivedReceived, cancelled, filled, worker stage updated, rejected, and assigned; limited to relevant agencies
Assignments and TimesheetsYesOnly records supplied by that agency
ExpensesYesOnly that agency's expenses
AfP and Payment NoticesYesOnly that agency’s records; excludes MSP-to-client and receivable records
Invoices and Credit NotesYesOnly that agency's records; excludes MSP-to-client records
Purchase OrdersYesNo
Trades and RatesYesNo

Purchase order endpoints reject agency-scoped API keys. Trade and rate events cover company configuration, including shared, tier, project, and agency-specific rate cards, so these webhook subscriptions are company-only. Agency access to individual trade/rate API records does not grant access to these webhook events.

These restrictions apply when creating or editing subscriptions, sending test events, and delivering live events. Remove company-only events from an agency subscription before using it.

Delivery contract​

Requidex sends a signed POST request with a JSON body to your configured URL. Duplicate and out-of-order deliveries are possible. Treat the event as a change notification, not a complete snapshot or an ordered transaction log.

Return a 2xx response after validating the event and accepting it for processing. A common receiver pattern is to verify the signature, persist or enqueue the event, then acknowledge it before performing slower API calls or downstream work.

Delivery headers​

HeaderMeaning
Content-Typeapplication/json
X-Requidex-EventEvent type, such as assignment_created
X-Requidex-Event-IdStable event ID, also present as payload id; reused across delivery retries
X-Requidex-TimestampISO 8601 UTC timestamp used for this attempt's signature
X-Requidex-SignatureHexadecimal HMAC SHA-256 digest of timestamp + '.' + rawBody

Custom headers configured on the subscription are also included. Keep custom header values and the signing secret out of logs.

Signature verification​

Use the webhook's signing secret, not an API key. Verify the original request-body bytes before parsing or transforming the JSON. Re-serialising a parsed object can change whitespace or property order and invalidate the signature.

  1. Read X-Requidex-Timestamp and X-Requidex-Signature.
  2. Reject malformed headers and timestamps outside your accepted clock window. A five-minute tolerance is a reasonable starting point; keep receiver clocks synchronised.
  3. Compute HMAC SHA-256 over the timestamp, a literal ., and the raw request-body bytes.
  4. Compare the received hexadecimal digest using a constant-time comparison.
  5. After verification, validate and deduplicate the event before processing it.

This Node.js helper verifies a raw Buffer and the two header values. Mount raw-body handling before any JSON body parser in your receiver.

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhook(rawBody, timestamp, signature, secret) {
  if (
    !Buffer.isBuffer(rawBody) ||
    typeof timestamp !== "string" ||
    typeof signature !== "string" ||
    !/^[a-f0-9]{64}$/i.test(signature)
  ) {
    return false;
  }

  const signedAt = Date.parse(timestamp);
  if (!Number.isFinite(signedAt) || Math.abs(Date.now() - signedAt) > 300_000) {
    return false;
  }

  const expected = createHmac("sha256", secret)
    .update(timestamp + ".")
    .update(rawBody)
    .digest();
  const received = Buffer.from(signature, "hex");
  return (
    received.length === expected.length && timingSafeEqual(received, expected)
  );
}

Timestamp validation limits replay exposure; it does not replace event-ID deduplication. Every retry signs the same event body with a fresh delivery timestamp.

Payload​

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "assignment_created",
  "createdAt": "2026-10-29T14:00:00.000Z",
  "data": {
    "assignment": {
      "id": "507f1f77bcf86cd799439011"
    }
  }
}
FieldTypeMeaning
idstringEvent identifier used for deduplication
typestringSubscribed event type
createdAtstringEvent creation time; distinct from each attempt's signing timestamp
dataobjectResource reference
Show child attributes
  • assignment object in this example; the resource key varies by event
    Show child attributes
    • id string — affected record ID
testbooleanPresent and true for test deliveries; omitted from normal events

Follow the event reference for its resource key, trigger conditions and subscription availability. Deleted-record events retain the ID, but the record cannot be fetched after deletion. For a delayed notification, a detail request returns the record's current state, not necessarily its state when the event was created.

Retry and failure behaviour​

Delivery succeeds on a 2xx response. Non-2xx responses, network failures and timeouts cause another attempt, up to the configured limit. Default delivery settings are a 10-second timeout per attempt and three attempts, with waits of one second before the second attempt and three seconds before the third. Do not depend on precise timing in your consumer.

Retries reuse the payload's event ID. After the attempts are exhausted, the delivery is recorded as failed; do not assume indefinite retry, guaranteed arrival or an automatic replay API. Review delivery logs in the Webhooks tab and reconcile important records through the API when necessary.

Your receiver should:

  • Deduplicate on event ID across retries and acknowledge already accepted events
  • Use a durable queue or stored event record before acknowledging work that must survive a receiver restart
  • Apply record updates safely when events arrive out of order
  • Reconcile critical datasets periodically rather than relying solely on notifications

Test and troubleshoot​

Send a test event from the Webhooks tab after configuring the URL and secret. Test payloads include test: true and a resource ID of test; verify the signature and acknowledgement, but do not request a real record for that ID.

For failed deliveries, check the receiving URL, network access, TLS configuration, signature verification, response status and processing time. Inspect the delivery log for attempt count and error details. Redact secrets and personal data before sharing diagnostics.

Event catalogue​

Event availability is defined by the company or agency subscription, not just by API-key scopes. Invoice events exclude drafts and applications for payment. AfPs have their own event family; payment-notice events cover standard and pay-less notices, including automatic issuance. Automatically issued notices send both issued and processed events. Agency delivery of invoice and credit-note events excludes MSP-to-client records.

AfP​

Assignments​

Credit notes​

Expenses​

Invoices​

Purchase orders​

Rates​

Requisitions​

Timesheets​

Trades​