Develop and test a webhook endpoint locally

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.

🚧

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 https://sh.rustup.rs -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 https://github.com/TrueLayer/truelayer-cli.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.

-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEEjjcekUMYJXvL1Dh3isvUphyO/hO+ODTys8GZP+UC6Uq98MTbxJjjO
CI2cZMH98CBQyB3tfLn+qT05ou2r3AJNraAHBgUrgQQAI6GBiQOBhgAEAOaYfeUE
IqUbYIKr08KS/6kFU/jMHqBzrT3cp0oKYo8B1UaxWG1Xv2SvRsG0y/zf6gK4IP17
eYHY3mjrEItx0pjSAAjOkEigEv1Bn/6kNDoiN5B6OBYSlVyckDers0g5Ee0sZRwO
dFh88TnSnj+OCKoIGMamoz6cvVUb0u+
-----END EC PRIVATE KEY-----