Web Hooks are a way for your application to be notified in real time about changes in ABRA Flexi.
The principle is simple: When a change occurs in the ABRA Flexi database, a POST HTTP request is sent (usually within a few seconds) to all registered URLs.
The request body contains a summary of all changes since the last hook call, in the same format returned by ABRA Flexi via the Changes API.
Note:
Notifications sent via Web Hooks do not count toward the daily API request limit.
Procedure
The Changes API (change tracking) must be enabled.
If you are not using our cloud (i.e., you have an on-premises or local installation), hooks must also be enabled in the ABRA Flexi Server configuration file flexibee-server.xml (directory locations for flexibee-server.xml):
...<entry key="enableHooks">true</entry>....
The reason is that when the server starts, the core engine must be started immediately (see also automatic core startup), which is a time-consuming operation. Note: if you have enableHooks set to true, there is no need to configure startKernel separately.
A hook is registered via a PUT (or POST) request to the URL /c/{firma}/hooks with the following parameters:
required |
|
The URL to be called | |
| Data format (possible values are |
optional |
|
| The version from which sending of subsequent changes will begin, i.e., from the next higher version. The default value equals the current global version ( |
| An arbitrary string that will be sent with every change notification in the HTTP header. It serves as a simple way to verify that an incoming notification belongs to your registered hook. The header key name is |
| Suppresses the functionality test of the provided URL. |
Example:
curl -u uzivatel:heslo -L -k -X PUT "https://localhost:5434/c/{firma}/hooks.xml?url=http://muj.server.cz/hook.php&format=XML&lastVersion=123&secKey=MyHookSecretToken0687"
Registration performs a test of the provided URL by sending an empty notification. If the response code is anything other than 2xx, the hook will not be registered. The test can be suppressed using the skipUrlTest parameter.
ABRA Flexi as of version 2017.1.1 supports SNI. This means it is possible to register hooks pointing to an HTTPS virtual host.
At this time, it is not possible to specify which records a hook should apply to — it will always be notified of all changes that occur in ABRA Flexi.
As usual, success is indicated by status code 200 and failure by code 400 (the response includes a text description of the cause).
A list of registered hooks is available at /c/{firma}/hooks; a hook can be unregistered via a DELETE request to /c/{firma}/hooks/{id}.
Hook Behavior on Error
If an error occurs while processing a hook, the server will retry the request. If the hook continues to fail, calls will begin to be delayed. Typically, if the service is completely unavailable, each subsequent call will be made later. For this purpose, a penalty is used, which represents the time between individual attempts.
You can retrieve the current penalty using GET:
curl -u uzivatel:heslo -L -k "https://localhost:5434/c/{firma}/hooks/{id}.xml"
To reset the penalty and trigger an immediate hook call, use a PUT request:
curl -u uzivatel:heslo -L -k -X PUT "https://localhost:5434/c/{firma}/hooks/{id}/retry"
Registered hooks are stored in the database, so hooks will still be dispatched after a server restart. The service guarantees that no change will be lost and that all changes will be delivered to the registered hook.
Hook Implementation Recommendations
The entire mechanism operates on a best-effort basis. This means that while we strive to deliver notifications as quickly as possible and avoid duplicates, you should account for the possibility that delays or duplicates may occur (i.e., the same request may be delivered more than once). To eliminate duplicates, you can process globalVersion.
Hook processing should take as little time as possible (< 15 seconds) and must not exceed 30 seconds, otherwise the call is considered unsuccessful. The response must have a status code of 200 (or 2xx) and should not contain any body. If any of these conditions are violated, the hook will be penalized (i.e., it will not be called for a period of time) and in extreme cases may be disabled entirely.
The ideal hook implementation only persists the received changes, with optional fast filtering for relevant changes and skipping of duplicates (already processed changes). The actual processing of received changes should run asynchronously in an independent thread.
Additional Supported Response Status Codes
In addition to the standard 200 status confirmation, hook processing supports the following response options:
301 (Moved Permanently) / 308 (Permanent Redirect)If the redirect points to a valid URL, the address of the registered hook will be updated and, after a short penalty period, change notifications will be sent to the newly recorded address.410 (Gone)It is assumed that the hook has been permanently removed, and ABRA Flexi will automatically unregister it.