A web application can be designed to notify you whenever an event happens by sending a message. The event could be any action or change of status in the app that you might be interested in.

One way for the app to implement the notification is to send a POST request to a particular URL, known as an endpoint. The POST contains some information to identify the event. You can use this in the endpoint handler to take some kind of action (for example, sending an email or updating a database record). A preconfigured POST designed to communicate event data like this is known as a webhook.

Smart Router implements webhooks for many different types of events that occur during payment processing. The webhook POST requests are usually sent to a single endpoint URL that you configure in the Dashboard. However, each time you create an invoice object, you can supply a custom webhook URL specifically for that Invoice if you need more control over the notifications. Note that the Smart Router data in the POST contains only the ID value of the event. You must use the API to retrieve the full details of the event using its ID.

See the webhooks section of the API reference to learn how to create a webhook handler on your web server. See the events section for a list of all the types of event notifications that Smart Router sends.

Configuring webhooks in the Dashboard

To set up a webhook URL, go to Dashboard › Developers › Webhook endpoints. Click on the Add webhook endpoint button, Enter your URL in the text box, then click the Add button to enable notifications. You can enable several webhook URLs at the same time, but note that all of them will receive the same notifications. All the active webhooks are listed on the table within the Webhook endpoints tab.

You can use HTTP basic authentication by setting a username and password within the webhook URL. For example: https://username:[email protected]/webhook.

In the Events tab there is a table that shows all events in the order they were generated, with the most recent first. Click on an event in this table to see all the data available for it, including if a Webhook was sent for that event, and any retries in case of unsuccessful response from your endpoint on the first attempt.

Managing pending transactions

A common use case for webhooks is managing transactions that are incomplete immediately after you capture them.

Smart Router returns a Transaction object for each successful capture. For card payments, the transaction is usually complete when this happens. However, a customer might later request a chargeback from the Payment Service Provider (PSP). This effectively cancels the payment, typically a short while after being captured.

Another example of delayed notification happens with alternative payment methods ,such as PayPal. These are usually asynchronous, so you might not get confirmation of a successful payment until a few minutes after it is started.

We recommend that you use webhooks to manage both of these cases. You can set up the webhook code to alert you about the changed status of the transaction or to respond to the change automatically. See the Transaction section of the API reference for the status changes a transaction can go through.