Skip to content
Switch to light mode

External Host Interface Integration Guide

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.

On this page

5.1 Required validation steps

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

  1. 1. Read the Payblr integration headers – Read the headers included with the inbound request from Payblr.
  2. 2. Confirm the signature algorithm – Confirm that x-ehi-signature-algorithm equals hmac-sha256.
  3. 3. Retrieve the raw request body – Retrieve the raw request body exactly as it was received.
  4. 4. Rebuild the signing payload – Rebuild the signing payload using the following format:<timestamp>.<rawRequestBody>
  5. 5. Compute the HMAC-SHA256 signature – Compute the signature using the shared secret provided during onboarding.
  6. 6. Compare the computed signature – Compare the computed signature with the value received in x-ehi-signature.
  7. 7. Validate the request timestamp – Validate that x-ehi-signature-timestamp is within the allowed anti-replay window.
  8. 8. Reject invalid requests – Reject the request if the signature validation or timestamp validation fails.
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:

ActionDescription
Reject the requestDo not process the EHI transaction payload.
Avoid balance impactDo not block, release, post, or adjust funds.
Log the failureInclude x-correlation-id, timestamp, validation reason, and endpoint received.
Return a controlled errorDo not expose sensitive validation details in the response.

Next steps

Continue to What Your System Receives.