Event-Driven Callbacks

Existem dois tipos de eventos: o tipo After (depois) e o tipo Before (antes). Eventos do tipo After são executados depois que um objeto é criado, atualizado ou excluído no Manager. Por exemplo, se um usuário criar uma app e houver um evento cadastrado como After App, a chamada será disparada logo após a criação da app no backend.

Já eventos do tipo Before são disparados antes de uma ação no Manager. Sendo assim, a criação/atualização/exclusão de um objeto poderá ser cancelada caso a chamada à URL cadastrada no event-driven callback falhe por qualquer motivo.

Um administrador cria um event-driven callback informando: a) qual o tipo de objeto que deseja observar; e b) uma URL. Quando objetos do tipo selecionado forem criados, alterados ou deletados, o API Manager fará uma requisição POST para a URL informada. Nesse caso, dizemos que o event-driven callback foi "ativado". O corpo da requisição POST conterá uma representação JSON do objeto em questão e mais alguns dados, como a ação (created, updated ou deleted) e o usuário responsável por ela.

O event-driven callback cadastrado pode ser disparado ANTES ou DEPOIS, dependendo do seu tipo (Before ou After). Depois de disparado, um listener é notificado de um evento e, se o callback for do tipo Before, o próprio callback pode bloquear a ação de criação/atualização/exclusão de um objeto qualquer, pois uma validação pode ser realizada antes que a ação ocorra de fato.

No caso de event-driven callbacks do tipo After, a ação (criação/atualização/exclusão) não será bloqueada, mas gerará uma mensagem de erro ou aviso alertando sobre o evento ocorrido.

Para criar um novo callback, clique no botão Create Event-Driven Callback, representado pelo símbolo + no canto inferior direito da tela. Uma janela modal será aberta para preenchimento dos dados.

Digite o nome (Name), escolha o tipo de evento que será observado no campo Event Type (veja tipos disponíveis abaixo) e informe a URL de um sistema criado para fins de notificação.

O campo Expected HTTP Status será habilitado apenas para eventos do tipo Before e deverá ser preenchido com o status HTTP esperado no retorno da chamada à URL cadastrada. Isso porque eventos desse tipo comparam o status cadastrado com o status retornado pela chamada para saber se podem prosseguir com a operação ou não.

O campo Request Headers não é obrigatório. Como já mencionamos, os callbacks são disparados a partir do monitoramento de ações de criação, atualização e exclusão de objetos. Se quisermos utilizar apenas uma ou duas das ações como gatilho, devemos inserir a propriedade action no campo Request Headers.

Depois de todos os campos estarem preenchidos corretamente, clique em Save.

Para editar um callback já cadastrado, clique no ícone , encontrado na coluna Actions da listagem de callbacks. Uma janela modal contendo as informações do callout será aberta, e você poderá alterar os dados. Quando terminar, clique em Save.

Para excluir um callback, clique no ícone , encontrado no campo Actions da listagem de callbacks .

Uma mensagem de confirmação será exibida. Clique em Ok para efetuar a remoção.

Caso ocorra algum erro durante a requisição POST para a URL informada (incluindo casos em que o host é desconhecido ou recusa conexões), o processamento do API Manager não será afetado e não serão feitas novas tentativas de POST.

Porém, o Manager mantém um histórico de todas as notificações que tentou enviar. Para ver o histórico de ativação de um event-driven callback, clique no link formado por data e horário na coluna Last triggered on na listagem de callbacks. Uma tela mostrará os detalhes do callback selecionado.

Muitas vezes, é desejável criar um callback para modificar ou complementar informações recebidas. Por exemplo, pode-se estabelecer que, quando uma app for criada, seja assumido o valor Java sempre que um valor do campo extra fields não seja especificado.

Porém, como o listener recebe o objeto depois que ele já foi criado, será necessário chamar a API do Manager para fazer a alteração.

Observe, porém, que alterações no Manager podem, por sua vez, disparar outros listeners. Deve-se tomar cuidado para não criar um loop infinito de eventos.

Note também que a API do Manager é, por si só, protegida com credenciais de acesso (para maiores detalhes, veja o tópico Users). Você deve criar credenciais do tipo "Integration" para que seu sistema interaja com o Manager de forma bem-sucedida.