Payments v3 webhook notifications

To receive notifications about payment or mandate statuses, set up webhooks. You configure the URI endpoint for webhooks in Console.

Supported notifications

Webhook structure

All our webhooks include these headers:

All incoming webhook requests must have their signatures verified, otherwise you risk accepting fraudulent payment status events. See Validate the received webhook signature.

Webhook bodies are encoded in JSON format with the following fields:

Each type of event may provide other fields. See the the specifications of the mandate or payment webhooks for more details.

Validate the received webhook signature

All incoming webhook requests must be verified via signature, or you risk accepting fraudulent payment status events.

📘

TrueLayer signing libraries

For the best development experience, we recommend that developers use our signing libraries to verify the Tl-Signature of the webhooks they receive.

E.g. Java com.truelayer.truelayer-signing

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

Verify the signature manually

For a full reference to our signing requirements, refer to our request signing docs on Github.

Webhook retry policy

We consider a webhook 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. If we continue to receive any other status codes than 2xx after retrying for 72 hours, we will discard the webhook.

We apply this retry policy for payments, payment links, payment refunds, payouts, and mandates.

Handling duplicated webhooks

TrueLayer can't guarantee that you only receive a single webhook notification for each payment status. As such, your integration should have logic that can handle receiving multiple webhooks for a given payment status.

For example, imagine TrueLayer sends an executed webhook, but doesn't receive a 200 response due to network issues from the recipient. In this case, TrueLayer sends an extra executed webhook as it can't confirm the previous one was received, regardless of the current status of the payment. The recipient's integration should be able to handle such possibilities.