Event-Driven Callbacks

There are two types of events: After and Before. The after-type events are executed after an object is created, updated or deleted on the Manager. For example, if a user creates an app and there is an After-App event registered, a call will be fired soon after the app is created in the backend.

As for before-type events, they are triggered before an action on the Manager. Then, the creation/update/deletion can be cancelled if the call to the URL registered in the callback fails for any reason.

An administrator creates an event driven callback by informing: a) which type of object to listen to; and b) an URL. When objects of the type selected are created, updated or deleted, the API Manager will perform a POST request to the URL informed. In this case, we say that the event-driven callback was "activated". The body of the POST request will contain a JSON representation of the object in question and some other data, such as the action (created, updated or deleted) and the user responsible for it.

The registered callback can be triggered BEFORE or AFTER an action, depending on its type. Once triggered, a listener is notified of an event and, if it is a before-type event, the callback itself can block the creation/update/deletion action of any object, because a validation can be performed before the event is confirmed.

In the case of after-type events, the action (creation/update/deletion) will not be blocked, but will generate an error or warning message.

To set up a new callback, click the Create Event-Driven Callback button, represented by the + symbol on the bottom right corner of the screen. A modal window will be opened for data entry.

Type in the name, choose the type of the event that will be listened to and inform the URL of a system created for the purpose of notification.

The Expected HTTP Status field will be enabled only when configuring calls for before-type events and it must be filled with the expected HTTP status returned in the call to the registered URL. This is because events of this type compare the registered status to the one returned in order to confirm whether they can proceed with the operation or not.

The Request Headers field is not required. As we have mentioned, the callbacks are fired from the monitoring of object creation, update and deletion actions. If we wish to use only one or two of these actions as a trigger, we must insert the property action in the Request Headers field.

After all fields are correctly entered, click Save,

To edit a registered callback, click the icon, found under the Actions column of the callbacks list. A modal window containing the data on the callback will pop up and you will be able to make your changes. When you are done, click Save.

To delete a callback, click the icon, found under the Actions column of the callbacks list.

A confirmation message will be displayed. Click Ok to go through with the exclusion.

If an error occurs during the POST request to the URL informed (including cases in which the host is unknown or refuses connections), the Manager processing will not be affected and no further POST attempts will be made.

However, the API Manager keeps a history of all the notifications it attempted to send. To view the activation history for an event-driven callback, click the link comprised of the date and time under the Last triggered on column of the callbacks list. A screen such as the next one will exhibit details of the callback selected.

You might wish to create an event-driven callback to modify or complete incoming information. For example, there can be a rule specifying that, when app is created, the value Java is assumed whenever there is an unspecified Extra fields value.

However, as the listener receives the object after it has already been created, you will need to make a request to the Manager API in order to make modifications.

Note, however, that changes on the Manager may, in turn, trigger other listeners. Care must be taken not to create an infinite loop of events.

Note, as well, that the Manager API is itself protected with access credentials (for more details, see the Users topic). You must create "Integration" credentials so that your system interacts with the Manager successfully.