Webhooks

You can use TxB Webhooks to have event updates proactively pushed from TxB to your server. Since webhooks only transfer data when an object has changed state, you can spend less time polling TxB APIs and receive fresher data (i.e., you only see data when something new has happened).

Currently, TxB supports webhook updates for two objects:

• Payments that you initiate. After you initiate a payment with TxB, we will send events back to you when that payment transitions from INITIATED to RELEASED to SETTLED.
• Customer service cases. After you create a customer service case with TxB via API, we will send events back to you when that case transitions to a CLOSED state.
• Payments that you receive. When an incoming payment is posted to your account, we will send you a webhook event stating payment was RECEIVED.

Available events

Case events are currently in Alpha and will be published when generally available.

Responses to a webhooks

Once you receive a callback from TxB, you're expected to respond with one of the following codes:

If TxB receives a 408, 429, or 5XX status code, then we will automatically retry to send the event. Otherwise, please use the payment status API to poll for an update. We also suggest using the payment status API periodically to reconcile payments which have not hit a terminal state for several days.

Event grouping

You can receive events individually (as they happen) or grouped together (e.g., if you plan to send a lot of payments and don't want to be bombarded with API requests). Below is an example showing how TxB can group multiple events into a single callback. If you request event grouping, then you will be required to configure both frequency and maximum events

• If maximum number of events is reached before frequency, you will be receiving webhooks more often
• If maximum number of events is not reached before frequency, you will be receiving webhooks as often as expected in line with the defined config

Example Grouping

• Event A - Payment accepted by TxB at 10:03 AM
• Event B - Payment released at 10:05 AM
• Event C - Payment settled at 10:15 AM
• Event D - Payment returned at 10:20 AM

If you opt for a maximum of 3 events in a group and a 15 minute update frequency, TxB will group events A, B and C and send them together at 10:15 AM, with event D coming through in the next update at 10:30 AM.

Note: We recommend a maximum event limit of 100 to avoid potential UX issues.

Anatomy of a webhook payload

{
    "deliveryId": "7a484093-f205-4004-9c5f-4c333527656e",

    ## Every message we send to you will be uniquely defined by a `deliveryId`
    ## One `deliveryId` can contain between 1 and N individual events
    ## The maximum number of a events in a message is configurable

    "events": [
        {
            "eventName": "PAYMENT_STATUS.RELEASED",

            ## eventNames correspond to the event trigger
            ## for example, PAYMENT_STATUS.RELEASED indicates
            ## that a payment you initiated has been released to
            ## a payment network


            "eventId": "7a484093-f205-4004-9c5f-4c333527656e",
            "eventTimestamp": "2021-02-01T16:56:46.384Z",

            ## the time at which an event was created.  Note that events
            ## may be delivered after the point at which they are created

            "eventData": {

            ## event data provides the object which has changed status
            ## which is, in thise case, a payment

                "identifiers": { ... },
                "paymentExecutedValueDate": "2021-06-21",
                "amount": 101,
                "paymentCurrency": "USD",
                "paymentStatus": {
                    "status": "RELEASED",
                    "statusTime": "2020-12-01T16:55:42.279Z"
                },
                ...
                }
            }
        }
}