Webhooks

Tristar can deliver outbound HTTPS webhooks when customer-scoped events occur (orders, notes, invoices, and related catalog events). Receivers expose an HTTPS endpoint; Tristar POSTs a signed JSON envelope for each subscribed event.

Webhooks are outbound only. There is no public API to create or manage webhook endpoints from API v2 — configuration is done in the Admin Portal.

Configuration

In the Admin Portal: Customer → Webhooks.

For each webhook endpoint configure:

A webhook only receives events that are both subscribed on that endpoint and active in the event catalog.

Delivery history is available in Admin Portal under Webhook Logs.

Delivery Mechanics

1. Application code publishes an event through IWebhookPublisher (or the invoice detection worker enqueues invoice.created).
2. Matching active customer webhooks are enqueued as Pending rows in WebhookDeliveryLog (Central DB).
3. A background delivery worker in API v2 polls about every 15 seconds, takes up to 25 due deliveries, and POSTs each payload as application/json.
4. HTTP client timeout per attempt is 30 seconds.

Retries And Statuses

Backoff after a failed attempt (before the next try):

delaySeconds = 2^attemptCount * 30

Examples after failed attempts 1–4: 60s, 120s, 240s, 480s. After the 5th failed attempt the delivery becomes DeadLetter.

Receiver Success Criteria

Treat the delivery as successful only when the receiver responds with an HTTP 2xx status. Non-2xx responses and transport errors mark the attempt failed and schedule a retry (until dead-lettered). Response bodies are stored truncated (up to 2000 characters) for troubleshooting.

Receivers should be idempotent: the same logical event may be retried, and publishers may use idempotency keys to avoid duplicate enqueue for the same webhook.

HTTP Headers

Every delivery POST includes:

Signature Verification

1. Read the raw request body bytes as UTF-8 text (do not re-serialize JSON before verifying).
2. Compute HMAC-SHA256(secret, body).
3. Encode the digest as lowercase hexadecimal.
4. Compare to X-Tristar-Signature using a constant-time comparison.

Reject the request if the signature is missing or does not match.

Envelope Payload

Bodies are JSON with camelCase property names:

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "event": "order.created",
  "occurredAt": "2026-07-22T15:30:00Z",
  "customerCode": "ABC001",
  "data": {}
}

Event Catalog

order.created / order.updated

Published when order save services create or update a draft/web order.

Common data fields:

Photo copy orders also include:

order.exported

Published after a successful export via order export (including create-with-export flows that call export).

note.created

Published when a note is added for a customer-scoped work order.

order.status_changed

Published from Notes/Add when a photocopy note includes an explicit milestone value.

Example:

{
  "id": "evt_d4e5f60718293a4b5c6d7e8f901a2b3c",
  "event": "order.status_changed",
  "occurredAt": "2026-07-22T15:33:00Z",
  "customerCode": "ABC001",
  "data": {
    "workOrder": "W123456",
    "orderType": "PhotoCopy",
    "facilityKey": "W123456-01",
    "milestoneCode": 1,
    "milestone": "None",
    "previousMilestoneCode": 1,
    "previousMilestone": "None"
  }
}

Desktop Winserve milestone changes (SetMilestone) are not yet wired; those paths remain a follow-up.

invoice.created

Published by a background detection worker that scans tenant invoice header tables for recently created work-order invoices (photocopy, WinservePlus/court, delivery, investigation). Idempotency keys prevent duplicate deliveries for the same invoice.

Example:

{
  "id": "evt_e5f60718293a4b5c6d7e8f901a2b3c4d",
  "event": "invoice.created",
  "occurredAt": "2026-07-22T15:34:00Z",
  "customerCode": "ABC001",
  "data": {
    "workOrder": "DD14809",
    "orderType": "PhotoCopy",
    "invoiceNumber": "1",
    "invoiceDate": "2026-06-23T00:00:00",
    "billToCustomerCode": "TRISTAR",
    "facilityLineItem": 1,
    "amount": 59.95
  }
}

Example Delivery

POST /webhooks/tristar HTTP/1.1
Host: example.com
Content-Type: application/json; charset=utf-8
X-Tristar-Event: order.created
X-Tristar-Delivery-Id: 42
X-Tristar-Signature: 3f1a9c...lowercasehex...

{
  "id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "event": "order.created",
  "occurredAt": "2026-07-22T15:30:00Z",
  "customerCode": "ABC001",
  "data": {
    "orderType": "Court",
    "webOrderId": "W123456"
  }
}

Verify X-Tristar-Signature against the exact body bytes shown above (or as received), using the webhook secret from Admin Portal. Respond with 2xx to acknowledge; any other status triggers retry/backoff.