Webhook Notifications

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

You can register to receive notifications about your payment or mandate statuses
via webhooks. The URI endpoint for the webhook can be
configured in the Console

Currently supported notifications

TypeDescriptionSpecifications
payment_authorizedNotification that a payment has been authorizeddocs
payment_executedNotification that a payment has been executeddocs
payment_failedNotification that a payment has faileddocs
payment_settledNotification that a payment has settleddocs
mandate_authorizedNotification that a mandate has been authorizeddocs
mandate_failedNotification that a mandate has failed to be createddocs
mandate_revokedNotification that a mandate has been revokeddocs

Webhook structure

All our webhooks will be sent with the following headers

FieldTypeDescription
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 run the risk of accepting fraudulent payment status events. See Validate the received webhook signature.

The webhook body will be encoded in JSON format with the following fields

FieldTypeDescription
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

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

We apply the above retry policy for payments, payment refunds, payouts, and mandates.

Validate the received webhook signature

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

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

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

📘

For the best development experience, use our signing libraries to verify signatures.

Verifying the signature manually

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


Did this page help you?