Webhook

A webhook lets you subscribe to certain events, which, when triggered, sends a webhook event payload in a POST message to your configured URL in real time. Webhook events are triggered when there is a change in status for a single transfer, a bulk transfer, or a standing order — TransferStatusChanged, BulkTransferStatusChanged, and StandingOrderStatusChanged, respectively. See the webhook protobuffer reference for payload definitions.

Here's the practical application of a Token webhook.

When a payment is initiated, you will need to determine if/when the payment requested is successful in order to notify your user of the transfer's status and take appropriate next steps, such as sending the user a receipt for payment or, if the transfer did not succeed, advising the customer with respect to a payment collection alternative before canceling the purchase altogether. Why is this important?

In some cases, completion of a payment initiation response from the bank takes longer than expected for reasons beyond the control of either the TPP or Token, resulting in a delay in receiving the transfer status from the bank, whether successful or rejected. While awaiting the transfer status in the bank's response to the original transfer request, the TPP could either continuously poll Token for an update on status, involving multiple calls made periodically, or it can rely on a Token webhook.

The webhook avoids protracted polling calls by the TPP for updates. Instead, upon any change in transfer status (the trigger), your Webhook URL immediately receives an HTTP POST message from Token containing the transfer status payload. During the interim, Token polls the bank for updates on the current status of the transfer so you don't have to. Here's the basic flow (hover to enlarge):

Note: The webhook is sent only when the transfer status returned by the bank is transitional; i.e., processing. When the status is conclusively final — either success or failure — the webhook is not sent.

The message Headers your Webhook URL will receive comprise the following:

Special Webhook Headers
Headers Description
Token-Event Name of the event type that triggered the delivery (Transfer or Recurring Payment)
Token-Signature Authenticates Token as the sender of the message and ensures that particular headers have not been modified in transit

To configure and test your Webhook:

  1. Expand Settings in the navigator, click Configuration, then select the Webhook tab.
  2. Enter the Webhook URL that will receive the updated status; e.g., https://yourWebServer.yourCompany.com.
  3. Select the Events that will trigger an update — Transfers, Recurring Payments, or both.
  4. Click Test to validate the Webhook URL.

  5. Click Okay to acknowledge the Event generated message. It confirms the URL to which the Webhook event has been sent and advises receipt within 1 to 3 minutes.

  6. Check that your Webhook URL received the event message (HTTP POST), then click Save to keep this configuration.

The HTTP POST you receive will contain a transactionId (optional, depending on bank support), transferId, refId, and the current transfer status. For a list of possible states, see Payment Status: Values and Meaning.