Skip to main content

How to receive YooKassa, T-Bank and Stripe webhooks on localhost

Create an HTTPS tunnel in ProximaClient to your service's port and put its link with the handler's path into the payment service's notification settings: payment notifications then reach the service on your computer as if it were a server on the internet.

Steps​

  1. Start the service on your computer, for example at localhost:3000, with a notification handler, for example /pay/notify.
  2. In ProximaClient, open "Tunnels" and click "Create tunnel". If you already have tunnels, it's the "+" button above the list.
  3. In "Protocol", pick HTTPS, "A website or API at a link of its own". A TCP tunnel's address won't do: payment services send notifications only to an https:// link.
  4. In "Destination address", enter the service's port: localhost:3000.
  5. Click "Create tunnel". Once the tunnel connects, copy the link with the "Copy public address" icon.
  6. In the payment service's dashboard, in the notification (webhook) settings, enter the link with the handler's path: https://your-link/pay/notify.
  7. Make a test payment and check that a request to /pay/notify shows up in your service's log.

If a notification doesn't arrive​

  • The service isn't running or listens on another port. The payment service gets a 502 answer. Start the service on the port from "Destination address".
  • The path in the settings is wrong. Compare the path in the notification settings with the handler's path in your code.
  • The link changed. While the tunnel runs, its link does not change; how long it is kept after the tunnel closes is on the "An HTTPS link to localhost" page. If the tunnel got a new link, enter it in the notification settings.
  • The link is closed with a login. The payment service doesn't know your login and gets a 401 answer.

Since app version 1.3.0

To let notifications through to a link with a login, add a rule for the handler's path on the "Security" tab, under "Path rules": "Addresses only" with the payment service's addresses from its documentation, or "No sign-in". More on the page about a login and password for a link.

How to keep out a forged notification​

Anyone can learn the link and send "payment succeeded" to it. So check the notification's signature in your code by the payment service's rules. T-Bank does not sign every field of a notification, and YooKassa does not sign its notifications at all: before you hand over the goods, check the payment status with a request to T-Bank (the GetState method) or to the YooKassa API.