Webhooks

Webhooks are necessary only for behind-the-scenes transactions. Many LotusPay requests (e.g. creating mandates or subscriptions) generate results that are reported synchronously to your code. These don’t require webhooks for verification.

NACH Debit requires using webhooks so that your integration can be notified about asynchronous changes to the status of mandate and ach_debit objects.

You might also use webhooks as the basis to:

• Update a customer's membership record in your database when a subscription ACH debit succeeds.

• Email a customer when a subscription ACH debit fails.

• Examine the Dashboard if you see that an ACH debit has failed.

• Log an accounting entry when a settlement is paid out.

Webhooks are configured in the Dashboard's Developers section. Here you can add a URL for receiving webhooks.

You can enter any URL as the destination for events. However, this should be a dedicated page on your server that is set up to receive webhook notifications. The URL will be notified of all event types.

Your current environment — whether you're using a test or live LotusPay account — determines whether test events or live events are sent to your configured URL. If you want to send both live and test events to the same URL, you need to create two separate settings in each environment.

LotusPay sends webhook notifications from the following static IP addresses. You may wish to whitelist these IP addresses in your network firewall.

Creating a webhook endpoint on your server is no different from creating any page on your website. With PHP, you might create a new .php file on your server; with a framework like Sinatra, you would add a new route with the desired URL.

Webhook data is sent as JSON in the POST request body. The full event details are included and can be used directly, after parsing the JSON into an Event object.

Webhook data is encrypted using the AES 128 algorithm. To decrypt the data, you will need to use your webhook key, which you can find in your LotusPay dashboard.

Here is sample code for decrypting the webhook post.

Steps for testing in Java:

1. Save the sample code as WebHookDecrypt.java

2. Replace the contents of and as per specification, and save the file.

3. Compile using javac WebHookDecrypt.java.

4. If compilation succeeds, run using java WebHookDecrypt.

5. You should see the decrypted event data in your console.

If you use an HTTPS URL for your webhook endpoint, LotusPay will validate 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.

LotusPay does not guarantee delivery of events in the order in which they are generated. For example, submitting a source might generate the following events: source.submitted mandate.active Your endpoint should not expect delivery of these events in this order and should handle this accordingly. You can also use the API to fetch any missing objects (e.g. you can fetch the source and mandate objects using the information from mandate.active if you happen to receive this event first).

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. All response codes outside this range, including 3xx codes, will indicate to LotusPay that you did not receive the webhook. This does mean that a URL redirection or a "Not Modified" response will be treated as a failure. LotusPay will ignore any other information returned in the request headers or request body.

If the initial webhook post fails for an event, we will re-attempt to post up to nine times with an exponential back off between attempts (in minutes: 1, 2, 4, 8, 16, 32, 64, 128, 256), ceasing if successful or after nine re-attempts (whichever is sooner). If you miss any event webhooks, you can reconcile either by manually retrying using the POST Event Webhook API endpoint, or you can query for the event with the GET Event API endpoint.

Before going live, test that your webhook is working properly. You can do so by using the test environment. To do this, add the endpoint to which test events should be sent. Next, click the Test Webhook button (visible to admin users only). Note that because these are dummy, test events, they will not map to real customers, mandates, ACH debits, or other objects in your account.

If your webhook script performs complex logic, or makes network calls, it's possible that the script would time out before LotusPay sees its complete execution. For that reason, you might want to have your webhook endpoint immediately acknowledge receipt by returning a 2xx HTTP status code, and then perform the rest of its duties.

Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you've processed, and then not processing already-logged events. Additionally, we recommend verifying webhook signatures to confirm that received events are being sent from LotusPay.