5. Security Requirements

Your system must validate that each forwarded request came from Payblr before processing the EHI payload.

Payblr signs outbound requests using an HMAC signature. Your system must validate the signature, timestamp, and payload before applying any business, balance, or ledger impact.

5.1 Required validation steps

Your system should validate each request from Payblr before processing the EHI message.

1. Read the Payblr integration headers – Read the headers included with the inbound request from Payblr.

2. Confirm the signature algorithm – Confirm that x-ehi-signature-algorithm equals hmac-sha256.

3. Retrieve the raw request body – Retrieve the raw request body exactly as it was received.

4. Rebuild the signing payload – Rebuild the signing payload using the following format:
   <timestamp>.<rawRequestBody>

5. Compute the HMAC-SHA256 signature – Compute the signature using the shared secret provided during onboarding.

6. Compare the computed signature – Compare the computed signature with the value received in x-ehi-signature.

7. Validate the request timestamp – Validate that x-ehi-signature-timestamp is within the allowed anti-replay window.

8. Reject invalid requests – Reject the request if the signature validation or timestamp validation fails.

Important raw payload rule

Your system must validate the signature using the raw request body.

Do not parse, reformat, reorder, normalize, trim, or reserialize the XML payload before computing the signature. Any change to the payload can produce a different signature result.

Recommended anti-replay window

Your system should reject stale timestamps.

Recommended anti-replay window: 5 minutes

Failed validation behavior

If signature validation fails, your system should: