Set up webhook notifications [Payments V2]

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 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.

Note: Legacy header X-Tl-Signature is also included, however verification using Tl-Signature should be preferred.

In the body you will see the following fields:

FieldTypeDescription
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
Tl-Signature: "detached..jws"

{
  "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 72 hours.

Validate the received webhook signature

We recommend developers to use our signing libraries to verify the Tl-Signature of the received webhooks.

Java com.truelayer.truelayer-signing

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