Skip to main content

​
Background

Deprovisioning webhooks send identity data from Lumos to an endpoint you control. This article describes how that connection is protected and exactly what the payload contains. Lumos sends every outbound webhook over HTTPS to an endpoint you register, and signs every payload. Your receiving system can confirm that the request came from Lumos and was not altered in transit. The payload carries only the business identity attributes needed to act on an offboarding event. It contains no HR-sensitive data, no compensation or personal record data, and no credentials.

​
How the connection is protected

  • HTTPS is required. Lumos rejects a plain HTTP endpoint when you configure the webhook. A payload can’t be 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. Lumos does not forward your data to a second destination.
  • Private addresses are blocked. Lumos rejects an endpoint that resolves to a private or internal network address. This prevents a webhook from pointing at internal infrastructure.
  • Source addresses are fixed. Outbound traffic leaves from a fixed set of IP addresses, so you can allowlist them at the network layer in front of your endpoint. For the current list, see Lumos IP addresses.

​
How the payload is authenticated

Each request carries an HMAC-SHA256 signature. Lumos computes it 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. For the header format and sample verification code, see Verifying Webhook Signatures. The signature gives your receiving side three guarantees:
  • The request came from Lumos. Only the two parties that hold the shared secret can produce a valid signature.
  • The body was not modified in transit. Any change to the payload invalidates the signature.
  • A captured request can’t be replayed. The timestamp is part of the signed material, so your receiver can reject anything outside an acceptable time window.
Lumos generates the signing secret from 256 bits of cryptographically secure randomness. Lumos stores it encrypted in a managed secrets service, scoped to your tenant and to that webhook. The secret is never written to the application database or into the payload. You can retrieve it when you configure your receiver, and rotate it by issuing a new one on the webhook settings page. You can also add custom headers to any webhook, such as a bearer token or an API key that your endpoint expects. Lumos stores those header values with the same encryption as the signing secret. Most teams use both: the signature proves authenticity and integrity, and the header credential lets the endpoint reject unauthenticated traffic before it does any work.

​
What the payload contains

The deprovisioning payload contains:
  • The user: email address, given name, and family name.
  • The account on the target application: the application’s own identifier for that account, plus email and username where they exist.
  • The application: its name and instance identifier.
  • The permissions or entitlements being removed, by name.
  • A comment field that describes the reason for the action.
  • Custom fields, only if your team configures them for that application.
That is the complete set. The payload contains no national identifier, date of birth, home address, employment or compensation record, manager chain, or authentication material. It describes an access change. It is not an identity record. The payload schema is fixed, not freely templated, and you can’t add arbitrary fields to it. A configuration mistake can’t cause additional identity attributes to start flowing to your endpoint later. For a full sample payload, see Deprovisioning Webhooks.

​
Auditability and delivery

Lumos records every webhook dispatch in the activity log, including failures. Each entry includes the target application, the affected user, the webhook, and the outcome. Your security team gets a record of what was sent, when, and whether it succeeded. Auditors typically ask for this record when they review an automated offboarding path. Deliveries are also time-bounded. A webhook that doesn’t respond within the configured window fails instead of hanging, and Lumos surfaces the failure. For timeout values and how to handle slow endpoints, see Understanding Webhook Task Failures in Lumos.