Testing and Troubleshooting Webhooks

Use this page once you have a receiver, such as the one in Building a Webhook Receiver.

Test locally

Send an example from any event page to your receiver. For example, save the newTransactions example as new-transactions.json, then run:

curl -i -X POST http://localhost:3000/webhooks/moneyhub \
  -H "Content-Type: application/json" \
  --data @new-transactions.json

You should get a 200 response. JWT webhooks are signed by Moneyhub, so you can't create valid ones locally. Test JWT verification end to end with a sandbox client.

Test end to end with a sandbox client

1. Make your receiver reachable over HTTPS, for example with a tunnelling tool, or deploy it to a test environment.
2. Set the webhook URL, format, and allowed events on a sandbox API client.
3. Trigger events with the test banks.
4. Check your logs, and the webhook list on the user's page under API users in the Admin portal. It shows each webhook's type, the status code your endpoint returned, and the payload.

The test banks can trigger these events:

Flushing pending batched events

To test batched webhooks without waiting for the batch interval, you can send all pending batched events for a client straight away from the Admin Portal:

1. Open the client in the Admin Portal.
2. Select Flush pending events.
3. Confirm when prompted.

All queued events for every user of the client are sent immediately to the configured batched webhook URL, using the same batched payload format described in Webhook Format. One batched webhook is sent per user. Once the flush completes, the Admin Portal shows how many events were sent and in how many batched webhooks.

Flushed events are removed from the queue, so they will not be sent again at the next scheduled batch. Events that arrive after the flush are queued as normal.

Flushing is only available:

• for sandbox clients
• to users with the own_clients_edit permission, for clients they own

Production checklist

• The endpoint uses HTTPS with TLS 1.2 or higher and is reachable from the Moneyhub source IP addresses.
• The endpoint responds with 2xx within 5 seconds, and processing happens afterwards.
• JWT webhooks are verified for signature, issuer, audience, and age. Keys are fetched from the JWKS URL, not hard-coded.
• If you use JSON format, you restrict requests to the Moneyhub source IP addresses or use a hard-to-guess URL path, and you fetch data from the API rather than trusting the payload.
• Processing is idempotent and doesn't depend on arrival order.
• Unknown event types are accepted and ignored.
• A scheduled job reconciles your data with the API.
• Failed and slow deliveries are monitored and alerted on.
• Only the events you need are enabled in allowed events.

Troubleshooting