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

Validate the received webhook signature

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

For example, 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?