Skip to main content

The signed request

Every request includes:
Verify HMAC-SHA256(secret, timestamp + "." + JSON payload), using a Unix timestamp in milliseconds and lowercase hexadecimal output. Use the complete flk_whsec_... secret string as the key and the exact request bytes, without parsing and reserializing JSON. Verify first, then decode and validate the body. The signed body’s IDs are authoritative; separate ID headers assist diagnostics. The body and event ID remain unchanged across retries. Each send has a fresh timestamp and signature. Allow at most five minutes of clock difference in either direction and keep your server clock synchronized.

Copy the verifier

The examples accept the current secret and, during rotation, the previous secret. They accept a matching v1 value, reject malformed headers and oversized bodies, and use constant-time comparisons.
For JavaScript, compile the TypeScript example with tsc or remove its type annotations. No payment-provider SDK is needed for verification.

Minimal raw-request diagnostic

For a Node IncomingMessage, read bounded chunks into a Buffer, pass it and the single flokit-signature header to verifyFloKit, and parse JSON only after successful verification. Set request and header timeouts and reject duplicate signature-header fields.
Raw request handling
Log only the verification result, response code, duration, and safe opaque references. Do not log the payload, email, answers, secret, or signing header. Verification authenticates the bytes; durable acceptance still requires the unique event transaction. For an isolated unsigned local diagnostic endpoint only, this checks basic HTTP connectivity. It does not test signature verification and must fail authentication at a production receiver:

Rotate a secret

The Company owner can rotate the secret on the Signing secret tab (or ask your FloKit contact). Install it in every receiver for the Company. During the 24-hour overlap, deliveries have signatures for both the active and retiring secrets. After the overlap, only the new secret is used; remove the retired secret from your receiver. Rotation does not change event IDs or request bodies.