7. Receive Updates with Webhooks

Much of what happens after a user connects an account or makes a payment happens in the background. Webhooks let Moneyhub tell your application when something changes, so you don't have to keep polling the API.

For example:

• After a user connects an account, we fetch older transactions in the background. newTransactions tells you when they arrive, and syncCompleted tells you when a sync has finished.
• After a user authorises a payment, paymentCompleted or paymentError tells you the outcome.
• When a connection is about to expire, reauthReminder tells you to ask the user to reconnect.

A webhook is an HTTPS POST request from Moneyhub to a URL you choose. Most webhooks contain IDs rather than full records, so you use the IDs to fetch the latest data from the API.

1. Create an endpoint

Create a route in your application that accepts POST requests and responds with 200 straight away. Building a Webhook Receiver has complete Node.js and Python examples that you can copy.

Check it works by sending it an example webhook:

curl -i -X POST http://localhost:3000/webhooks/moneyhub \
  -H "Content-Type: application/json" \
  --data '{"id":"abe168ce-1b2f-4c38-9c92-db5730485cb3","eventType":"syncCompleted","userId":"5c79210bbac25ecb5e71ac40","payload":{"processingStatus":"success"}}'

To receive webhooks from Moneyhub, the endpoint must be reachable over HTTPS. While developing, you can use a tunnelling tool or deploy to a test environment.

2. Configure your API client

In the Admin portal, edit your sandbox API client and set:

• Webhook URL: the HTTPS URL of your endpoint
• Webhook format: JSON is simplest to start with. Use JWT in production so you can verify that webhooks come from Moneyhub
• Allowed events: for this guide, newTransactions, syncCompleted, paymentCompleted, and paymentError

3. Trigger some webhooks

Use the test banks:

• Connect an account with the Open Banking Mock bank, as in Connect An Account. You should receive newTransactions and syncCompleted.
• Make a payment, as in Payments. You should receive paymentCompleted. Use the reference REJECTED to receive paymentError instead.

You can see every webhook sent to a user, with the status code your endpoint returned, on the user's page under API users in the Admin portal.

4. Act on the webhooks

Use the IDs in each webhook to fetch the latest data:

• For newTransactions, fetch the transactions by ID, as in Querying Data.
• For paymentCompleted and paymentError, retrieve the payment using paymentId.

Do this after responding to the webhook, not before. Moneyhub waits up to 5 seconds for a response.

Before you go live

Webhooks are sent once and are not retried, and they can arrive in any order. Before going live, work through the production checklist, and see Building a Webhook Receiver for how to verify, store, and process webhooks reliably.