Set up webhook notifications [Payments V2]

📘

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:

Tl-Signature: "detached..jws"

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

See the full list of 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);