Webhook

Listen to events in your Walletpay account on your webhook endpoint so your integration can automatically trigger reactions.

Send events to your AWS account

We’re launching support for receiving Walletpay events in Amazon EventBridge in private beta. Sign up to get early access.

Webhook Event Object

The Webhook Event object we send to your webhook endpoint provides a snapshot of the object that changed.

Example Event Payload

The following event shows a order payed.

{
  "event_type": "order.payed",
  "payload": {
    "id": "1brOrx2ZWZBpBUvZwXKQmoEYga2",
    "uid": "unique-order-identifier",
    "provider": "telegram",
    "wallet": "wallet",
    "currency": "USDT",
    "amount": "1",
    "completedAt": "2024-05-23T16:47:06.340451Z"
  }
}

Response

200

Return a 200 status to indicate that the webhook event was received successfully

Best practices for using webhooks

Review these best practices to make sure your webhooks remain secure and function well with your integration.

Handle duplicate events

Webhook endpoints might occasionally receive the same event more than once. You can guard against duplicated event receipts by logging the event IDs you’ve processed, and then not processing already-logged events.

Only listen to event types your integration requires

Configure your webhook endpoints to receive only the types of events required by your integration. Listening for extra events (or all events) puts undue strain on your server and we don’t recommend it.

You can change the events that a webhook endpoint receives in the Dashboard or with the API.

Handle events asynchrounously

Configure your handler to process incoming events with an asynchronous queue. You might encounter scalability issues if you choose to process events synchronously. Any large spike in webhook deliveries (for example, during the beginning of the month when all subscriptions renew) might overwhelm your endpoint hosts.

Asynchronous queues allow you to process the concurrent events at a rate your system can support.

Receive events with an HTTPS server

If you use an HTTPS URL for your webhook endpoint (required in live mode), Walletpay validates that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid server certificate. Walletpay webhooks support only TLS versions v1.2 and v1.3.

Roll endpoint signing secrets periodically

The secret used for verifying that events come from Walletpay is modifiable in the Webhooks section of the Dashboard. For each endpoint, click Roll secret. You can choose to immediately expire the current secret or delay its expiration for up to 24 hours to allow yourself time to update the verification code on your server. During this time, multiple secrets are active for the endpoint. Walletpay generates one signature per secret until expiration. To keep them safe, we recommend that you roll secrets periodically, or when you suspect a compromised secret.

Verify events are sent from Walletpay

Walletpay sends webhook events from a set list of IP addresses. Only trust events coming from these IP addresses.

Additionally, verify webhook signatures to confirm that received events are sent from Walletpay. Walletpay signs webhook events it sends to your endpoints by including a signature in each event’s x-signature header. This allows you to verify that the events were sent by Walletpay, not by a third party. You can verify signatures either using our official libraries, or verify manually using your own solution.

The following section describes how to verify webhook signatures:

Retrieving your endpoint’s secret

Use the Webhooks section of the Dashboard. Select an endpoint that you want to obtain the secret for, and find the secret on the top right of the page.

Walletpay generates a unique secret key for each endpoint. If you use the same endpoint for both test and live API keys, the secret is different for each one. Additionally, if you use multiple endpoints, you must obtain a secret for each one you want to verify signatures on, and Walletpay starts to sign each webhook it sends to the endpoint.

Preventing replay attacks

A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks, Walletpay includes a timestamp in the x-timestamp header. Because this timestamp is part of the signed payload, it’s also verified by the signature, so an attacker can’t change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload.

Our libraries have a default tolerance of 5 minutes between the timestamp and the current time. You can change this tolerance by providing an additional parameter when verifying signatures. Use Network Time Protocol (NTP) to make sure that your server’s clock is accurate and synchronizes with the time on Walletpay’s servers.

Walletpay generates the timestamp and signature each time we send an event to your endpoint. If Walletpay retries an event (for example, your endpoint previously replied with a non-2xx status code), then we generate a new signature and timestamp for the new delivery attempt.

Quickly return a 2xx response

Your endpoint must quickly return a successful status code (2xx) prior to any complex logic that could cause a timeout. For example, you must return a 200 response before updating a customer’s invoice as order paid in your accounting system.