QEHSQEHS
Sign inBook a demo

Developer portal

Webhooks

Push events to your systems as they happen in QEHS. Every delivery is signed with HMAC-SHA-256 and retried with exponential backoff for 24 hours.

Event catalog

EventDescriptionPayload shape
record.createdA new record is committed to a module.{ id, moduleKey, createdAt, createdBy, payload }
record.updatedAny field or workflow state changes on a record.{ id, moduleKey, changes[], updatedAt, updatedBy }
record.transitionedA workflow transition fires (including state name before/after).{ id, moduleKey, from, to, actor, at }
record.deletedA record is soft-deleted.{ id, moduleKey, deletedAt, deletedBy }
module.publishedA Composer version is published to production.{ moduleKey, version, publishedBy, publishedAt }
user.provisionedSCIM or self-sign-up created a new user.{ userId, email, provisionedAt, source }
user.deprovisionedA user is disabled or removed via SCIM.{ userId, at, source }
attachment.uploadedAn attachment is completed and virus-scanned.{ attachmentId, recordId, sizeBytes, mimeType }
export.completedAn asynchronous export job has a downloadable artefact.{ jobId, downloadUrl, expiresAt, kind }
billing.subscription.updatedPlan, seat count, or trial state changed (tenant-owner scope).{ tenantId, plan, seats, status, effectiveAt }

Signature verification

Every outbound delivery includes an X-QEHS-Signature header of the form t=<timestamp>,v1=<hex-hmac>. Re-compute the HMAC-SHA-256 of <timestamp>.<raw-body> using your endpoint's shared secret and compare with a constant-time equality check. Reject anything older than 5 minutes.

// Node.js / TypeScript
import crypto from 'node:crypto';

export function verify(body: string, header: string, secret: string): boolean {
  const [ts, sig] = header.split(',').map((p) => p.split('=')[1]);
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${body}`)
    .digest('hex');
  const match = crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex'));
  const fresh = Math.abs(Date.now()/1000 - Number(ts)) < 300;
  return match && fresh;
}

Delivery semantics

  • At-least-once delivery. Use the X-QEHS-Delivery-Id header to dedupe.
  • 8 retry attempts over ~24 hours with exponential backoff (1m, 5m, 15m, 1h, 4h, 10h, 20h).
  • Any non-2xx response (or timeout > 15s) triggers a retry.
  • A delivery failing all retries moves to the dead-letter queue; admins receive an email.
  • Replay individual deliveries from https://app.qehsethos.com/settings/webhooks.

Setup

  1. Open https://app.qehsethos.com/settings/webhooks and click "Add endpoint".
  2. Enter the URL, pick events, optionally filter by module key.
  3. Copy the shared secret once — you will need it to verify signatures.
  4. Click "Send test" to trigger a sample delivery to your endpoint.