Payments v3 webhook notifications

Set up webhooks to get updates on payments or mandates in our Payments API v3.

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

Supported notifications

TypeNotification descriptionSpecification
payment_authorizedThe payment was
payment_executedThe payment was
payment_failedThe payment
payment_creditableThe payment has been deemed ready to be credited to the end
payment_settledThe payment has
payment_settlement_stalledThe payment did not reach settled status after a certain amount of
external_payment_receivedThe external payment has
mandate_authorizedThe mandate was
mandate_failedThe mandate creation
mandate_revokedThe mandate was
payment_link_payment_createdA payment was created through a payment
payment_link_disabledThe payment link was
payout_executedThe payout was executed. Notification structure differs between closed-loop, open-loop or business account
payout_failedThe payout failed. Notification structure differs between closed-loop, open-loop or business account
refund_executedThe refund was
refund_failedThe refund

Webhook structure

All our webhooks include these headers:

X-TL-Webhook-TimestampISO-8601 TimestampTime that the webhook was sent to you. This will be in the following format: 2020-05-18T10:17:47Z.
TL-SignaturestringJSON web signature with a detached payload of the form {HEADER}..{SIGNATURE}

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:

typestringType of the event
event_idstringA UUID for the event
event_versionstringVersion of the event type

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


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.