Develop and test a webhook endpoint locally

All the tools you can use to test Payments v3 on your local app.

Developing a webhook receiving endpoint and webhook verification can be tedious. To speed up the process of testing the changes to your code, you can use Cloudflare tools to route webhooks to your local app.


Payments API webhooks are routed to your locally running app.


These features are only available for the sandbox environment.

Using Docker

Our public Docker image can be used to generate webhooks and also route locally.

You can acquire the image by pulling:

docker pull truelayer/truelayer-cli

Once the Docker image is pulled, you can use it for generating webhooks and also routing them locally.

Routing webhooks to local apps

docker run truelayer/truelayer-cli route-webhooks --to-addr http://localhost:8080 --client-secret <client-secret> --client-id <client-id>

Generate payments and webhooks

Generating executed webhook

docker run -v <folder-to-private-key-pem-fle>:/keys truelayer/truelayer-cli generate-webhook --client-secret <client-secret> --client-id <client-id> --private-key <private-key> --kid <kid> executed

Generating failed webhook

docker run -v <folder-to-private-key-pem-fle>:/keys truelayer/truelayer-cli generate-webhook --client-secret <client-secret> --client-id <client-id> --private-key <private-key> --kid <kid> failed

Using the source

This is a step by step guide to set up a tunnel to your local machine to receive webhooks in sandbox.

1. Install Cargo

First, you need to install Cargo. On Linux and macOS, use the command below:

curl -sSf | sh

For Windows and more information, you can refer to this documentation.

After successful installation of cargo, run the following command to install TrueLayer command line tool.

2. Install TrueLayer CLI tool

cargo install --git

Routing webhooks to local apps

Run the following command to start routing sandbox webhooks:

truelayer route-webhooks --to-addr http://localhost:8080 --client-id <your-client-id> --client-secret <your-client-secret

Replace the local address to whatever your application locally uses.

In this example, any webhooks generated in the sandbox environment will now be routed to the address localhost:8080 on your machine.

Generate payments and webhooks

You can also quickly generate webhooks using TrueLayer CLI tool. For this you need the private key you had generated before, and its public key pair uploaded on the console. You can find the kid of this public key from the console and pass it to the CLI tool.

Generating executed webhook

truelayer generate-webhook --private-key <path-to-private-key-pem> --client-id <client-id> --client-secret <client-secret> --kid <public-key-key-from-console} executed

Generating failed webhook

truelayer generate-webhook --private-key <path_to_private_key_pem> --client-id <client_id> --client-secret <client_secret> --kid <public-key-id-from-console> failed


Your private key is the pair of the public key you have uploaded to Console on the settings page. Learn more in our documentation about request signing.