Webhook Security for Offboarding Payloads

Last updated: September 17, 2026

Background

Deprovisioning webhooks send identity data from Lumos to an endpoint you control, so it's worth being precise about what is protected and what is actually in the payload.

Nothing is transmitted in the clear. Every outbound webhook is sent over HTTPS to an endpoint you register, and every payload is cryptographically signed, so your receiving system can prove the request came from Lumos and was not altered in transit. The payload itself is deliberately narrow. It carries the business identity attributes needed to act on an offboarding event and nothing more, with no HR-sensitive data, no compensation or personal record data, and no credentials of any kind.

How the connection is protected

  • HTTPS is required. A plain HTTP endpoint is rejected outright when the webhook is configured, so there is no path by which a payload gets sent unencrypted, even by misconfiguration.

  • Redirects are not followed. If your endpoint or anything in front of it responds with a redirect, the delivery fails rather than silently forwarding your data to a second destination.

  • Private addresses are blocked. An endpoint that resolves to a private or internal network address is rejected, which prevents a webhook from being pointed at internal infrastructure.

  • Source addresses are fixed. Outbound traffic leaves from a fixed set of IP addresses, so you can allowlist those addresses at the network layer in front of your endpoint. The current list is in Lumos IP addresses.

How the payload is authenticated

Each request carries an HMAC-SHA256 signature computed over a timestamp plus the request body, using a signing secret unique to that webhook. The signature and the timestamp travel together in the X-Lumos-Webhook-Signature header. See Verifying Webhook Signatures for the header format and sample verification code.

That gives your receiving side three guarantees at once.

  • The request originated from Lumos, because only the two parties holding the shared secret can produce a valid signature.

  • The body was not modified in transit, because any change to the payload invalidates the signature.

  • A captured request can't be replayed, because the timestamp is part of the signed material, so your receiver can reject anything outside an acceptable time window.

The signing secret is generated as 256 bits of cryptographically secure randomness. Lumos stores it encrypted in a managed secrets service, scoped to your tenant and to that individual webhook, and never writes it into the application database or into the payload. You can retrieve it when configuring your receiver, and rotate it by issuing a new one on the webhook settings page.

You can also add your own custom headers to any webhook, for example a bearer token or an API key that your endpoint expects. Those header values are stored with the same encryption as the signing secret. Most teams use both, the signature to prove authenticity and integrity, and a header credential so the endpoint can reject unauthenticated traffic before it does any work.

What the payload contains

The deprovisioning payload contains:

  • The user, meaning email address, given name, and family name

  • The account on the target application, meaning the application's own identifier for that account, plus email and username where they exist

  • The application, meaning its name and instance identifier

  • The permissions or entitlements being removed, by name

  • A comment field describing the reason for the action

  • Custom fields, only if your team explicitly configures them for that application

That is the complete set. There is no national identifier, no date of birth, no home address, no employment or compensation record, no manager chain, and no authentication material. The payload is a work order describing an access change, not an identity record.

The payload schema is also fixed rather than freely templated. You can't add arbitrary fields to it, which is a security property in its own right, since no configuration mistake can cause additional identity attributes to start flowing to your endpoint later. A full sample payload is in Deprovisioning Webhooks.

Auditability and delivery

Every webhook dispatch is recorded in the activity log with the target application, the affected user, the webhook involved, and the outcome, including failures. That gives your security team a queryable record of exactly what was sent, when, and whether it succeeded, which is typically what an auditor asks for when reviewing an automated offboarding path.

Deliveries are also time-bounded. A webhook that doesn't respond within the configured window fails rather than hanging, and the failure is surfaced rather than passing silently. See Understanding Webhook Task Failures in Lumos for the timeout values and how to handle slow endpoints.