Working with Webhooks

As discussed in Webhook under Configuration in Understanding Dashboard Settings, a webhook (also called a web callback or HTTP push API) is an automated method that lets Token provide you with real-time updates regarding payment initiation status and/or the status of standing order submissions. Consequently, configuring a Token webhook eliminates the need to poll for data to get the latest status.

When configured to do so, Token webhooks notify you when the following events occur:

  • Payment status changes for a single immediate payment. Final status of the payment may not be immediately known, so Token polls the bank periodically until the final status is available. Polling stops once the final status is received.
  • Standing order setup status changes. When setting up a standing order, the final status of the initiation may not be immediately known. Therefore, Token polls the bank to determine if the final status is available. Token stops polling once the final status is received.

You can configure your webhook using ether (a) the dashboard or (b) the API. Guidance for the former is discussed in Understanding Dashboard Settings > Configuration > Webhook. Guidance for the latter, using the API, is discussed below.

Setting Up Webhooks using the API

You'll need to configure the event(s) for which you wish to receive webhook notifications. This is often referred to as "event subscription."

To subscribe to an event, make a PUT /webhook/config call and place the details in the body, structured like this:

{

    "config": {

        "type": [ "TRANSFER_STATUS_CHANGED", "STANDING_ORDER_STATUS_CHANGED"],

        "url": "your-webhook-url.com"

    }

}

The respective fields are defined in the following table:

Fields in the Webhook Config Request
Field Description/Subfields Required/Optional
config Contains the configuration parameters Required
type Specifies the types of webhook to configure; available values: INVALID, TRANSFER_STATUS_CHANGED, and STANDING_ORDER_STATUS_CHANGED; default = INVALID Required
url Specifies the webhook URL that will receive status updates Required

Once configured, you can retrieve your current webhook configuration with a GET /webhook/config call. Because you are limited to one configuration, no request parameters are needed. The response will specify the type and url properties in the config object.

{

    "config": {

        "type": [ "TRANSFER_STATUS_CHANGED", "STANDING_ORDER_STATUS_CHANGED"],

        "url": "your-webhook-url.com"

    }

}

You can delete your webhook at any time with a DELETE /webhook/config call. No request parameters are required. If successful, an empty 200 response is returned.

Receiving Webhook Notifications

For transfers, the webhook url you configure will receive an HTTP POST message with the following message Headers and transfer status payload:

// Token Headers

token-signature:84p7oxffpN6fui9FGCq8YWNYPAFqzJTEET_JtnddYRCnZl_Nt7J4QYBGAgJzVr_MK_DFi75CBOlzef0CWGEmBw

token-event:TRANSFER_STATUS_CHANGED

 

// Body

{

    "createdAtMs": "1624649550800",

    "id": "c95dd32d-8248-48e8-bbc9-a6391377156e",

    "transferStatusChanged": {

        "refId": "4iWznLG7pgTSWAddN",  // refId sent in the original transfer request

        "bank_payment_status": "ACSC" // original status of submitted request

        "status": "SUCCESS", // updated status

        "status_reason_information": "AcceptedSettlementCompleted" // see Understanding Payment Initiation Status

        "transferId": "t:GDK27TpvHk7AqjfUMKKqD6RXpusXEztxWbN49Acw43qx:5zKZFPab",

        "transactionId": "x:HLSpd8758wq43QYBGAgJzVr_MK_DFi75CBOlzef0CWGEmBw"

    }

}

For standing orders, the headers and payload change to a structure like this:

// Token Headers

token-signature:84p7oxffpN6fui9FGCq8YWNYPAFqzJTEET_JtnddYRCnZl_Nt7J4QYBGAgJzVr_MK_DFi75CBOlzef0CWGEmBw

token-event:STANDING_ORDER_STATUS_CHANGED

 

// Body

{

    "createdAtMs": "1624649550800",

    "id": "c95dd32d-8248-48e8-bbc9-a6331977156e",

    "standingOrderStatusChanged": {  

        "standingOrderStatus": {

            "refId": "4iWznLG7pgTSWAddN",  // refId sent in the original standing order request

            "bank_standing_order_status": "PENDING", // original status of submitted requested

            "status": "SUCCESS", // updated status

            "submissionId": 3Psodjflg0ds9sGH9 // submission id of the standing order

            // bank-dependent standing order ID; optional

            "standingOrderId": "t:GDK27TpvHk7AqjfUMKKqD6RXpusXEztxWbN49Acw43qx:5zKZFPab"

        }

    }

}

See Swagger Object and Field Definitions for additional details.