Set up webhook notifications

Learn how to set up webhooks and understand the notifications we send to you when you create a payment initiation request.


This feature is in private beta and is currently available to a limited number of clients. To join our private beta, contact Client Care.

When the status of a payment changes, we send a single_immediate_payment_status_changed event to the webhook_uri specified when creating the payment initiation request.

When TrueLayer send a webhook to the specified webhook_uri, we will include a X-TL-Signature header, containing a signature in the form of a JWS token that you can use to validate that the request came from us. Instructions for validating this signature can be found below.

In the body you will see the following fields:

event_typestringdescribing which event is detailed. In this case the event will be single_immediate_payment_status_changed
event_bodyobjectcontaining both the single_immediate_payment_id as a string and the status as a string
X-TL-Signature:  "a JWS token"

  "event_type": "single_immediate_payment_status_changed",
  "event_body": {
    "single_immediate_payment_id": "77a75df0-af60-4785-8e91-809ac77ca8e3",
    "status": "executed"

For a list of all the available payment statuses, check out our page on polling for payment statuses.

Webhook retry policy

We consider a webhook as having been successfully delivered when we receive a success status code (2xx) from your webhook URI.

If we receive any other status code (for instance, if your API is temporarily unavailable), we will start retrying. Our retry policy is jittered exponential backoff. We will immediately perform some fast retries and then start waiting increasingly longer. We will keep retrying for up to 24 hours waiting approximately 15 minutes between delivery attempts.

Validate webhook signature

The value of the X-TL-Signature header contains a JSON Web Signature (JWS) with a detached payload. It takes the form {HEADER}..{SIGNATURE}.

The JWS header contains the following values:

algstringThe algorithm used to sign the webhook. We currently use the RS256 algorithm.
jkustringThe URI of the JSON Web Key Set (JWKS), a hosted page where a list of public keys owned by TrueLayer can be found.
kidstringThe ID of the key used to sign the webhook, used to retrieve the correct key from the JWKS.
iatintThe time that the JWS was issued, represented in Unix time (number of seconds since 1970-01-01T00:00:00Z).

To verify the signature:

  1. Verify the jku field in the token header matches the expected value, as shown below. If not, the signature should be rejected as invalid.
    • Sandbox:
    • Production:
  2. Use the jku value to retrieve the JWKS. This may be cached for some time, but if verification fails the JWKS must be re-retrieved to ensure that all keys are up to date. Keys may be rotated or revoked at any time by TrueLayer.
  3. Get the relevant public key by using the kid to find the relevant value from the JWKS.
  4. Use a JWT library to verify the JWS headers combined with the payload (the webhook request body) matches the signature provided in the token. The algorithm used to verify the signature must be the one in the alg header of the JWS.

Check out our code samples for signature validation.

Did this page help you?