With the webhook feature on debtor level it is possible to receive a notification when an event is completed. Using this feature renders it no longer necessary to constantly require the API to call information (pulling) until new information is available. The webhook will sent a notification when new information is available to be called up.
How to activate the webhook feature
The "Webhook settings" dashlet can be found on debtorlevel under "Integrations". To activate this feature follow the next steps:
1. Go to the "Webhook settings" dashlet on debtorlevel.
2. Create and add a new webhook setting by clicking on the "+ new webhook settings" icon:
3. In the pop-up, fill in the name of the webhook setting, the endpoint (the point where the notification should be received when actions are completed), and the actions for which a notification is desired (run finish or journals finish action). Then, check the "active" checkbox to turn the webhook on, and click "save" to save these settings.
4. After saving the setting, the webhook is activated for the specific debtor. A notification is sent to the indicated endpoint when the journals are created and runs finalised. An overview of all sent webhooks over a given period can be found at the bottom of the dashlet. This can be used to track down if a certain event triggered the webhook.
List of webhooks available
Get notified when a run is finished. It applies for all run types (normal, retro-active correction, pre-run).
|Journals Finish||Get notified when the creation of journals are finished|
|Wage Tax Declaration Created||Get notified when a wage tax declaration is created|
|Wage Tax Declaration Sent||Get notified when a wage tax declaration is sent|
|Pension Export Created||Get notified when a pension export is created|
|Pension Export Sent||Get notified when a pension export is sent|
How to use webhooks
After the setup of the webhook settings described above, the events configured will start triggering notifications.
For example, if a partner needs to know in real time when a run is finished, the event "Run Finish" can be configured. Then, after receiving the notification, the partner can use the call Run_GetList to retrieve further details about the new run that has been just finished.
The same logic applies to the other events available. First you get the notification, then you pull the data you need out of the API, instead of pulling reguarly.
Configure webhooks via the API
To facilitate the life of partners and API users that need to use webhooks, it's possible to manage them via the API.
- WebhookSettings_GetEvents - get list of all available events that can be configured. You shall use the id to setup.
- WebhookSettings_Get - get which webhooks are currently configured for an specific debtor
- WebhookSettings_Insert - configure a new webhook
- WebhookSettings_Delete - delete a specific webhook