Event-Driven Callbacks

Throughout the normal operation of the API Manager, there usually are situations in which we wish to notify external systems. For example, when important objects are created, updated, or deleted. To do this, the API Manager allows setting up event-driven callbacks, which are external calls from pre-configured triggers (events).

The Event-Driven Callbacks page is accessed via the side menu, inside Notification. On this screen, you can create, change, delete and view existing event callbacks, as well as verify the activation history of each separate call.

event driven callbacks

You can register multiple callbacks for the same type of object. For example, you might want to perform two different actions (such as sending an email and generating a log entry) in response to the same event (e.g., an app being created). To reduce coupling, two callbacks could be created, one to http://host/send-email and to http://host/generate-log.

Here are some examples of how this feature can be used:

Whenever…​ …​ do this:

a user signs up in the Developer Portal

send an email to an administrator.

an app is created

create sandbox objects for this app.

an app is created

create temporary tokens to speed up developer experimentation.

a policy is modified

make sure no rule allows more than 100 accesses per second

How it works

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.

callbacks diagram

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.

If an after-type event and a before-type event are registered for the same type of object, both will be executed, but before-type events take precedence over after-type.

Creating event-driven callbacks

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.

create callback

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,

Event types

Callbacks can be configured to be triggered before or after actions of creation, update and deletion of these objects: access token, API, app, developer, plan and system configuration.

The following pages provide examples of the request bodies sent in each case:

Editing an event-driven callback

To edit a registered callback, click the icon edit 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.

edit callback

Deleting an event-driven callback

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

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

delete callback

Errors and activation history

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.

callback errors

Calling the Manager API in your event-driven callbacks

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.

Thanks for your feedback!

Share your suggestions with us!
Click here and then [+ Submit idea]