Callbacks

Why use callbacks

When building integrations with the Direct Debit API, you might want your applications to receive requests as they occur, so that your backend systems can execute actions accordingly.

To enable the callbacks, you need to register the callback endpoints. After you register them, Ayoconnect can push event data to your application’s callback endpoint when events happen. Ayoconnect uses HTTPS to send callbacks to your endpoints as a JSON payload.

Receiving callbacks is particularly useful for listening to asynchronous events such as when a customer’s bank confirms a payment, a customer binds a card, a recurring payment succeeds, or when collecting subscription payments.

Callbacks behavior

This section helps you understand different behaviors to expect regarding how Ayoconnect sends callbacks to your endpoints.

Retry behavior

Ayoconnect attempts to deliver a callback to your endpoint up to 3 times. 1st attempt will happen as soon as we complete the transaction/ binding. 1st retry will happen after 1 min of 1st attempt fails. 2nd retry will happen after 2 min of 1st retry fails. The thrid attempt will happen after 5 min of 2nd retry happens.

You can manually retry sending individual callbacks to your endpoint from the Merchant Dashboard.

Realize that the automatic retries continue, even if you manually retry transmitting individual callbacks to a given endpoint and the attempt is successful.

Disable behavior

Ayoconnect attempts to notify you of a misconfigured endpoint by email if the endpoint hasn’t responded with a 2xx HTTP status code for multiple days in a row. The email also states when the endpoint will be automatically disabled.

Event ordering

Ayoconnect doesn’t guarantee delivery of callbacks in the order in which they’re generated. For example, a full Direct Debit flow might generate the following requests:

• card binding callback
• payment callback

Your endpoint shouldn’t expect delivery of these requests in this order and needs to handle delivery accordingly.

Best practices

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

Handle duplicate requests

Callback endpoints might occasionally receive the same request more than once. You can guard against duplicated requests by making your event processing idempotent. One way of doing this is logging the requests you’ve processed, and then not processing already-logged requests.

Listen to all the callbacks

Configure your endpoints to receive all the requests. Listening to only some requests (instead of all requests) can make your integration behave unexpectedly and we don’t recommend it.

Handle requests asynchronously

Configure your handler to process incoming callbacks with an asynchronous queue. You might encounter scalability issues if you choose to process requests 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 concurrent requests at a rate your system can support.

Receive callbacks with an HTTPS server

If you use an HTTPS URL for your callback endpoint, Ayoconnect 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.

Verify requests are sent from Ayoconnect

Ayoconnect sends callback requests from a set list of IP addresses. Only trust requests are coming from these IP addresses. This allows you to verify that the requests were sent by Ayoconnect, not by a third party.

Quickly return a 2xx response

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

Callback headers

The following headers are included in all the callbacks received from Ayoconnect: