Getting started
Information in a Moneybird account is constantly changing. If you want to perform actions based on these changes, webhooks help you to achieve this. Instead of querying the API at a certain interval, Moneybird will notify you about changes to information in the bookkeeping.
Usage
Webhooks are useful in a broad range of situations. When the state of a sales invoice changes, Moneybird will perform an HTTP request to the URL you provide. Based on the payload of the request, you can determine which action you need to perform.
How it works:
- You need a URL that Moneybird can call to deliver the payload. The Moneybird servers must be able to access this URL.
- You can add HTTP basic authentication or other token authentication in the URL, as long as the URL stays valid.
- Your URL always needs to respond with a
200HTTP status. Upon registration this is checked. - When your URL responds with another HTTP status code, Moneybird will retry to deliver the push 10 times. The time interval between retries is gradually extended.
- After each push, Moneybird will store the last HTTP status code and HTTP body. Using the webhooks API, you can retrieve this information for debugging purposes.
You can register as many webhooks as required in an administration. Registration is done by sending a POST request to the webhooks API.
We strongly recommend that you use a secure HTTPS endpoint for receiving payload from Moneybird. If you use unencrypted HTTP, anyone on the network may be able to listen in on sensitive information like contacts and invoices.
Idempotency
Webhook push requests include an Idempotency-Key header. This value is unique for each individual webhook push. Since Moneybird retries a push if a non-200 status code is received, you can use this value to ensure that your backend never processes the same push twice.
Events
It is also possible to subscribe to events. When an event you are subscribed to occurs, Moneybird will perform an HTTP request to the URL you provide. A full list of available events can be found at Events. If you decide to not subscribe to any events the old implementation will be used (notifications after state changes of sales invoices). This is to prevent existing webhooks from failing. If you would like to subscribe to a group of events, you can use the top level name of the event (eg. estimate).