Using webhooks to respond to events

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 event that occur during the processing of a payment. 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 data that Smart Router passes 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 notification that Smart Router sends.

Configuring webhooks in the Dashboard

To set up a webhook URL, go to Dashboard › Developer API › Events. Enter your URL in the text box at the top of the page, then click the Create 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 at the top of the page.

Below the webhook list 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.

Managing pending transactions

A very common use case for webhooks is to manage transactions that are not complete 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 it was first 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 Transactions section of the API reference for a list of the status changes that a transaction can go through.