Verifying Webhook Signatures

When a PNSL event delivery includes signature headers, verify the delivery before trusting it. The Events contract identifies the signature, key, and algorithm through the X-Signature, X-Key-Id, and X-Algorithm headers. Use the algorithm returned for the referenced public key; do not hard-code a single algorithm.

How webhook signatures work

1. Preserve the delivery body

The Events contract models a JSON envelope with id, timestamp, type, and data. Preserve the received body before parsing it so your verification implementation can use the form required by the declared algorithm.

Example Webhook Body:

{
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "timestamp": "2026-06-23T14:05:09Z",
    "type": "credit-account.created",
    "data": {
        "creditAccountId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
        "clientId": "b7e8c1a2-9f43-4d2e-8a6b-1c2d3e4f5a6b",
        "code": "AXI000221",
        "currency": "USD",
        "creditLimit": "10000.00",
        "principalOutstanding": "0.00",
        "totalRepaymentAmount": "0.00",
        "totalInterestAmount": "0.00",
        "availableBalance": "10000.00",
        "paymentRails": "ZENUS_BANK",
        "status": "ACTIVE"
    }
}

2. Key Identification and Headers

Axiym provides the necessary metadata for verification within the HTTP headers of the POST request:

Header	Value	Description
X-Signature	string	The signature supplied with the delivery.
X-Key-Id	string	The ID of the public key used for signing.
X-Algorithm	string	The algorithm declared for the delivery.

3. Verification Steps

Upon receiving a webhook from Axiym, your application should:

Capture the Raw Body: Access the raw, unparsed bytes of the HTTP request body before any JSON deserialization occurs.
Extract Headers: Retrieve the values of X-Signature, X-Key-Id, and X-Algorithm.
Load the Public Key: Retrieve GET /webhooks/public-keys/{publicKeyId} and confirm the returned key is active.
Validate Algorithm: Use the algorithm declared by the delivery and returned with the public key.
Perform Verification: Verify the signature using the received body in the form required by that algorithm.
Authenticity: If the verification is successful, the message is authentic. If the check fails, the request must be rejected.

Security Considerations

Body integrity: Preserve the body before parsing it and follow the requirements of the declared algorithm.
Key rotation: Use X-Key-Id to select the current public key rather than assuming a permanent key.
Replay protection: Evaluate the event timestamp against a time window appropriate for your system.
Fail Securely: If the signature does not match or the headers are missing, return a 401 Unauthorized status and do not process the data.

Conclusion

Verify every signature before trusting or processing the event payload.