Below we’ll walk you through the benefits of webhooks and provide a guide to help you configure and integrate with Bud's webhooks.

Having trouble with webhooks? Check out our webhook FAQ.

Prerequisites

Prior to using any of Bud’s webhooks, you must perform the following steps:

1. Sign up to the Bud Console
2. Get API Keys and authenticated access
3. You should now be able to configure webhooks via the Bud Console, but one of following steps are required for us to make calls to your webhooks.
   1. Setup Bud Connect
   2. Setup Bud Connect with your own license
   3. Setup Bud Payments

Why use webhooks at Bud?

The Bud platform hosts various asynchronous API endpoints. This is where you submit a request and then receive a task id in the response. You then make a request to a second endpoint in order to get the status of the task (and sometimes the final result).

There are two methods to know when the task has finished processing: (i) by polling the second endpoint, i.e. making several requests to it every X seconds until a result is provided; or (ii) by receiving a callback, i.e. Bud will send a request to a specific webhook URL to let you know that the task has finished processing and the result is ready to be collected.

When working with large datasets or where processing the task can take a significant amount of time, polling can be an inefficient method of retrieving the final result. Every time the second endpoint is called when the task hasn't completed processing, compute resources are used by both parties - and if this is repeatedly called, the resource consumption becomes wasteful. Ideally this should be avoided.

👍

We therefore recommend, that you use the second option to receive a callback rather than polling for the result.

Many of our asynchronous endpoints also offer callbacks and will call your configured webhook URL. These callbacks can be found in our API Reference on the Bud documentation. By opting to use callbacks, both parties reduce the amount of compute resources that are used when communicating with asynchronous endpoints.

Example:

The POST /v1/open-banking/refresh asynchronous endpoint (here) allows you to initiate the task to retrieve the latest data from a customer account (if the consent exists). You can check the status of the task via the GET /v1/open-banking/refresh/{task_id} endpoint (here). Polling this endpoint repeatedly, when it is not ready, wastefully consumes your compute resources (by making the call) as well as ours (to determine the status). Thankfully, the POST /v1/open-banking/refresh endpoint (here) offers a few callbacks, one of which is the RefreshCompleted callback. When configured, this callback will call the webhook URL configured in your Bud Console - letting you know that the refresh has completed as well as various other data.

Example response for RefreshCompleted:

{  
  "data": {  
    "task_id": "030c78b0-617c-4649-9319-e07569362a14",  
    "task_type": "refresh",  
    "customer_id": "82a90a04-4bdf-446a-932e-fb559ea99c29",  
    "status": "Completed",  
    "result": "success",
    "has_new_transactions": "true",
    "reconnect_required": "false",
    "provider": "Capital_One"
  }  
}

Configuring webhooks

Configuring webhooks at Bud couldn’t be easier. You can configure this in the Bud Console under the Project page.

By clicking view on a project, you’ll be presented with an option to Setup a webhook:

You can select the events you would like to subscribe to, and specify the callback URL you would are using.

You can then see a list of registered webhooks, with the option to activate/deactivate them, as well as the option to register webhooks for other URLs

You may be required to build a webhook service to ensure you are ready to consume callbacks - more details about this can be found below.

How to integrate with Bud webhooks

You must provide an endpoint that we can call to send data about the callback (this will be the webhook URL set in the Bud Console). This means that the endpoint must be publicly reachable.

All our webhooks are provided with an X-Signature and X-Signing-ID header. The X-Signing-ID includes the public key id which should be used to verify the X-Signaure header (i.e. the signed request body JWT). A list of public keys can be found in our Bud Callback Assets.

We will also include a payload in the webhook call - the format of the payload will vary depending on the callback type, however, all callback payloads follow a similar structure. Below are the three currently supported payload types with some sample data:

Open banking aggregation webhooks:

{
  "data": {
    "consent_id": "e8d6beb1-0a3d-42bb-a11b-033e06a1becf",
    "customer_id": "8888ec25-90b0-4ea4-80d8-5173cecf533c",
    "provider": "Bank_Of_Bud",
    "result": "success",
    "status": "Completed",
    "task_id": "030c952e-0332-4e0c-8484-9f60ab5596cd",
    "task_type": "connect"
  }
}

Customer management webhooks:

{  
  "data": {  
    "result": "success",  
    "task_id": "d7d5cfbf-bb37-423e-a6b8-d3062b388324",  
    "customer_id": "c1762607-a7a5-42dc-ba2e-4f9507b4d399"  
  }  
}

Payment webhooks:

{  
  "data": {  
    "payment_id": "fee4f871-cb81-42f1-8aea-3de4937ab955",  
    "service": "domestic-single-payment",  
    "user_id": "client-defined-user-id",  
    "event": "payment.success"  
  }  
}

Webhook Retries

If your webhook endpoint responds with one of the following status codes we will attempt to redeliver it up to 10 times, with an exponential backoff:

408 Request Timeout
425 Too Early
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

Any other status code we will abort attempting to redeliver the webhook.

Bud webhook support

We are continuing to grow our webhook support, and we will add more over time. The best way to see if an endpoint supports webhooks, is to check the API Reference on the Bud documentation. The most commonly used webhooks are detailed below:

Open banking aggregation webhooks

Open Banking sync completed - works for both connect and refresh tasks. This will fire when an open banking connect or refresh task (in both the TSP and TPP scenarios) either completes or fails. The result field returned in the response will provide some details as to why a given task may have failed (if the status field is equal to “Failed”).

Open banking connection completed - This will fire when an open banking connect task (in both the TSP and TPP scenarios) either completes or fails. The result field will provide some details as to why a given task may have failed (if the status field is equal to “Failed”).

Open banking refresh completed - This will fire when an open banking refresh task (in both the TSP and TPP scenarios) either completes or fails. The result field will provide some details as to why a given task may have failed (if the status field is equal to “Failed”).

🚧

You must integrate with Bud Connect to receive aggregation webhooks

Please visit our Setup Bud Connect or Setup Bud Connect with your own license guides to see how

Customer management webhooks

Customers Deleted - used to inform clients when a customer has been removed from the Bud platform and all their subsequent data has been deleted.

Payment webhooks

Single payment status updated - used to provide an update to clients when the status of a single payment has either succeeded or failed.

Standing order status updated - used to provide an update to clients when the status of a standing order payment has either succeeded or failed.

Schedule payment status updated - used to provide an update to clients when the status of a scheduled payment has either succeeded or failed.

🚧

You must integrate with Bud Payments to receive payment webhooks

Please visit our Setup Bud Payments guide to see how

FAQ

Q: It is difficult to determine from the payload, which callback is being triggered - how might we determine which callback was called?

• A: We suggest clients use a different callback URL for each webhook. This has the added benefit to the client to scale individual webhook URL endpoints, as it is likely some callbacks will trigger more frequently than others.
• A: For clients that wish to use a single endpoint - we plan to extend the payloads of our webhook calls to include an event field, to better identify which callback was triggered. This is currently in place for Payment webhooks.

Q: We have set up a webhook service and are not receiving any calls. What could be the issue?

• A: Please make sure the endpoint is publicly reachable - we often find clients do not provide a valid and reachable webhook URL - whether because it is only reachable behind a VPN, we are refused access, or the provided URL is not valid.
• A: If it was working before and has stopped, we will likely be aware of the issue and we will be actively trying to resolve it.

If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via a support request or check our FAQs.