Signature verification

Each request includes a Turrilum-Signature header of the form:

Turrilum-Signature: t=1714000000,v1=abc123def456...

To verify: concatenate the timestamp t, a period ., and the raw request body. Compute HMAC-SHA256 using your webhook signing secret, then compare against v1. Reject requests where the timestamp is more than 5 minutes old.

import { createHmac } from "node:crypto"

function verifySignature(secret, rawBody, signatureHeader) {
  const [tPart, v1Part] = signatureHeader.split(",")
  const t = tPart.replace("t=", "")
  const v1 = v1Part.replace("v1=", "")

  const payload = t + "." + rawBody
  const expected = createHmac("sha256", secret)
    .update(payload)
    .digest("hex")

  const isValid = expected === v1
  const age = Date.now() / 1000 - Number(t)
  return isValid && age < 300 // reject if >5 min old
}

Event types

All event payloads share the envelope { id, event, created_at, data: { ... } }.

Candidates

Applications

Jobs

Offers

Note: action: "send" marks the offer as sent and fires offer.sent, but does not deliver an outbound email — email delivery is handled via the Turrilum UI.

Interviews

Interviews created via the API use provider=api. No calendar events are created or updated — calendar integrations are session-scoped to the Turrilum UI.

Indeed (active)

Disposition sync to Indeed is active once Indeed ATS Partner credentials are configured in the Super Admin settings (or the INDEED_CLIENT_ID / INDEED_CLIENT_SECRET / INDEED_EMPLOYER_ID env vars are set). The provider calls the Indeed Job Sync GraphQL applicantStatusUpdatemutation and maps Turrilum milestones to Indeed's status enum: APPLIED, REVIEWED, INTERVIEWING, OFFER_EXTENDED, HIRED, REJECTED, WITHDRAWN. Only applications that arrived via the Indeed Apply webhook (those whose id starts with indeed_) are synced; internally-added candidates are silently skipped.

LinkedIn RSC / Apply Connect (requires partner approval)

LinkedIn disposition sync is a stub — the dispatch layer detects the provider key and no-ops with a logged warning until LinkedIn partner credentials are set. To activate it, the following must be procured:

1. LinkedIn Partner Program approval — apply at linkedin.com/talent-solutions/recruiter-system-connect. LinkedIn requires an existing ATS customer base and a signed partner agreement before they issue credentials.
2. OAuth 2.0 app in the LinkedIn Developer Portal — create an app at developer.linkedin.com, then request the Recruiter System Connect and Apply Connect products for that app. These products are gated and only available after partner approval.
3. Environment variables to provision: LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET, LINKEDIN_APPLY_WEBHOOK_SECRET (for verifying inbound Apply Connect webhooks). Once set, the stub in lib/dispositions/providers/linkedin.ts becomes active.
4. Inbound Apply Connect webhook — register your webhook URL (/api/linkedin/apply, to be built) in the LinkedIn Developer Portal. LinkedIn will POST applicant data there; store applicationId from the payload into application.externalId so disposition reports can reference it.
5. Disposition endpoint — once credentials are live, replace the stub body in sendDisposition() with: POST https://api.linkedin.com/v2/jobs/{externalJobId}/applicantTrackingStatuses with body { applicantId, status }, using the OAuth 2.0 client-credentials token with RSC scopes.

Until all five steps are complete, Turrilum will log a single warning per server instance and skip LinkedIn disposition syncs without affecting recruiter actions.