Webhooks

MoNa supports the usage of custom webhooks, which are used for synchronization of it's content with other third party repositories or associated MoNa installations.

To register a webhook, you have to utilize the REST api at this point in time.

Register

To register a web hook, please utilize curl to call the API and send the following envelop with it

url: http://mona.fiehnlab.ucdavis.edu/rest/webhooks

method: POST

data:

{ "name": "hook abc", "url": "http://localhost:9999/webhook", "description": "a simple hook for testing" }

Please ensure you are providing your authentification information!

This should look something like this:

#!bash

curl -H "Content-Type: application/json" -H "Accept: application/json" http://mona.fiehnlab.ucdavis.edu/rest/webhooks -X POST -d '{ "name": "hook", "url": "http://localhost:9999/webhook", "description": "a simple hook for testing" }' -H "Authorization: Bearer "my token""

As response you will receive your created web hook. The name has to be unique across all web hooks.

Unregister

to unregister your web hook, you will have to provide an admin token and execute a DELETE request

url: http://mona.fiehnlab.ucdavis.edu/rest/webhooks/<NAME>

method: DELETE

This should look something like this:

#!bash

curl -H "Content-Type: application/json" -H "Accept: application/json" http://mona.fiehnlab.ucdavis.edu/rest/webhooks/hook -X DELETE -H "Authorization: Bearer "secret admin token"

Responding to triggered events

MoNa, will automatically call your url, every time one for the following events occurs:

• add - registers a new spectrum in your system
• delete - notifies you that this spectrum was deleted from the main system and deletes it from your system
• update - notifies you that a spectrum was update and updates it in your system

This call will be done as a GET request and will add the following information to your url:

• the ID of the spectrum which was modified
• the TYPE of event

In our example the invoked URL is going to look like this:

http://localhost:9999/webhook?id=ID&type=TYPE

The actual implementation what your system is going todo, will be depend on you.

Triggering a webhook

MoNa, will normally trigger webhooks automatically, when this is required of the system. If you would like to trigger webhooks for a specific id and event manually. This can be archived by invoking the following URL.

method: POST

url: http://<YOUR_IP_OR_NAME>:<PORT>/rest/webhooks/trigger/<ID>/<EVENT>

And provide your local administration token.

• ID is the id of the spectrum, you would like to trigger
• EVENT is the event you would like to trigger. This can be add,update or delete

Master/Slave synchronization

MoNa allow to synchronize all it's slaves to the main master, utilizing it's web-hooks to push notifications to every registered slave in the system. Please be aware that every slave is only allowed to have 1 master, but can have an unlimited amount of slaves.

Defining the master to synchronize against

By default the main MoNa website is registered as master, which is http://mona.fiehnlab.ucdavis.edu and it's port 80.

To overwrite the value, you will need to modify the docker-compose.yml file and edit the webhooks section.

The following variables have to be updated/added

• mona.rest.server.port
• mona.rest.server.host

Please don't forget to add the -D in front of them, or you will receive error messages during startup.

#!yaml

  webhooks:
    image: eros.fiehnlab.ucdavis.edu/mona-webhooks-server:latest

    depends_on:
      - proxy
      - mongodb
    entrypoint: ./wait-for-it.sh proxy:8080 -t 3600 --strict -- java -Xmx512m -XX:+UseParallelGC -Dspring.cloud.config.uri=http://config:1111 -Dspring.profiles.active=docker -Dmona.rest.server.host=mona.fiehnlab.ucdavis.edu -Dmona.rest.server.port=80 -jar *.jar
    ports:
    - "4440:4444"

Since MoNa is opensource, you can just fork the bitbucket repository, to get easy access to the required files and keep track of your custom changes.

Webhooks

please register your publicly reachable server on the main server as a web hook. You will now receive all future updates automatically.

The web hook url of your local MoNa server, will be the following:

http://<YOUR_IP_OR_NAME>:<PORT>/rest/webhooks/sync

Since you most likely are synchronizing against an existing server, you might want to have all the initial data. You can easily get these, using the build in pull system from MoNa

Pull endpoint

Using the pull endpoint, permits you to download all spectra, which are registered in your remote master. If you like, you can limit these data, with a query, if you only want to populate your database from a subset of it's available data.

to start a pull request, please utilize curl with the following options:

method: POST

url: http://<YOUR_IP_OR_NAME>:<PORT>/rest/webhooks/pull

And provide your local administration token.

If you like to utilize a custom query, please modify your url to look like this:

url: http://<YOUR_IP_OR_NAME>:<PORT>/rest/webhooks/pull?query=metaData=q='name=="collision energy" and value=="50 eV"'

This would now only pull the spectra, which match this query.

Push endpoint

MoNa also provides as PUSH endpoint, to push all the spectra on a master, to all it's registered slaves. Please be aware that this endpoint should be used very carefully, since it can create a very high load on the master and the slaves.

to start a push request, you need to invoke the following url:

method: POST

url: http://<YOUR_IP_OR_NAME>:<PORT>/rest/webhooks/push

And provide your local administration token.

If you like to utilize a custom query, please modify your url to look like this:

url: http://<YOUR_IP_OR_NAME>:<PORT>/rest/webhooks/push?query=metaData=q='name=="collision energy" and value=="50 eV"'

This would now only push the spectra, which match this query.