Verify webhook signatures

When you receive a live webhook about a payment, payout, refund or mandate status, verify that it is signed correctly to ensure that the event actually did come from TrueLayer. To do this, ensure that the public key on your webhook URI matches the private key that TrueLayer holds. We strongly recommend that you use our signing libraries to verify the Tl-Signature of webhooks.

For example, our Java library:

Verifier.verifyWithJwks(jwks)
        .method("POST")
        .path(path)
        .headers(allWebhookHeaders)
        .body(body)
        .verify(webhookSignature);

To verify a webhook successfully, you must not change the content of the body in any way before passing it to the signing libraries.

Make sure the object that you’re using to decode the body of a webhook is UTF-8 compliant and doesn’t change the content in any way. Use primitive types like bytes or strings instead of complex objects (such as JsonNode or JsValue) that could slightly alter the content.

Make sure the byte content is not altered from the original payload as sometimes it could look the same in debug.

Verify webhooks without using libraries

🚧

Manual verification

We recommend that you use our signing libraries for easier integration.

To verify webhook signatures, refer to our Github reference implementations and examples.

In particular, see this page, which describes the signing and verification scheme.