Web Hooks are a way for your application to learn about changes in ABRA Flexi in real time. The principle is simple: when a change occurs in the database, a POST request is sent — usually within a few seconds — to all registered URLs. The request body contains a list of changes since the last hook call, in the same format you get through the Changes API.
💡 Sending notifications from Web Hooks does not count toward the daily API request limit.
Procedure
For hooks to work, two conditions must be met:
The Changes API (change tracking) must be enabled.
Hooks must be enabled on the server. This applies only to installations on your own or a local server — in our cloud, this is set up for you.
On your own server, hooks are enabled in the configuration file flexibee-server.xml (where to find it):
...
<entry key="enableHooks">true</entry>
...
The reason is that when the server starts, it needs to immediately start the core — a time-consuming operation, see automatic core startup. If you have enableHooks set to true, you no longer need to set startKernel.
⚠️ As long as hooks are not enabled on the server, the entire endpoint /hooks — including the listing — returns the error 400 with the message Hooks are not enabled in flexibee-server.xml.
Registering a hook
A hook is registered by sending a PUT request (or POST) to /c/{firma}/hooks with the following parameters:
Parameter | Required | Meaning |
| yes | The URL to be called — for example |
| yes | Data format; possible values are |
| no | The version from which subsequent changes will start being sent, i.e., from the next higher version. The default value equals the current global version ( |
| no | An arbitrary string that will be sent with every change notification in the |
| no | With the value |
Registration example:
PUT https://demo.flexibee.eu/c/demo/hooks.xml?url=http://muj.server.cz/hook.php&format=XML&lastVersion=123&secKey=MyHookSecretToken0687
Registration tests the provided URL by sending an empty notification. If the return code is anything other than 2xx, the hook will not be registered; the test can be suppressed using the skipUrlTest parameter. As usual, success is indicated by code 200 and failure by code 400, whose response includes a text description of the cause.
Starting with version 2017.1.1, ABRA Flexi supports SNI, so it is possible to register hooks pointing to an HTTPS virtual host.
ℹ️ It is not possible to specify which records a hook should apply to — a hook is always notified of all changes that occur in ABRA Flexi. Your application must handle filtering for relevant changes itself.
Listing and unregistering
The list of registered hooks is available at /c/{firma}/hooks; a hook can be unregistered by sending a DELETE request to /c/{firma}/hooks/{id}.
Hook behavior on error
If an error occurs while processing a hook, the server tries to resend the requests. If the hook continues to fail, its calls will start being delayed — typically, if the service is completely unavailable, each call will occur later and later. For this purpose, a penalty is used, which represents the time between individual attempts.
The current penalty for a specific hook is returned by GET:
GET https://demo.flexibee.eu/c/demo/hooks/{id}.xml
Resetting the penalty and immediately calling the hook is done with the PUT request:
PUT https://demo.flexibee.eu/c/demo/hooks/{id}/retry
Registered hooks are stored in the database, so hooks will still be sent after a server restart. The service guarantees that no change is ever lost and that all changes are delivered to the registered hook.
Recommendations for hook implementation
The entire mechanism operates on a best effort basis. This means that even though we try to deliver notifications as quickly as possible and avoid duplicates, you need to account for the possibility of delays or duplicates — i.e., that we may deliver the same request more than once. To eliminate duplicates, process globalVersion.
🚨 Hook processing should take as little time as possible (under 15 seconds) and must never exceed 30 seconds, otherwise the call is considered unsuccessful. The response must have status code 200 (or 2xx) and should not contain any body. If any of these conditions are violated, the hook is penalized — it will not be called at all for some time — and in extreme cases it may even be disabled entirely.
An ideal hook implementation only persists the received changes, with possible quick filtering for relevant changes and skipping of duplicates, i.e., changes that have already been processed. The actual processing of the received changes should run asynchronously in an independent thread.
Other supported response status codes
In addition to the standard confirmation with status 200, hook processing also supports the following options in responses:
Response status code | What ABRA Flexi does |
| If the redirect leads to a valid URL, the address of the registered hook is updated, and after a short penalty, change notifications will be sent to the newly registered address. |
| The hook is assumed to have been permanently canceled, and ABRA Flexi will automatically unregister it. |