Webhook Plugin

1 vote
Dependency:
compile ":webhook:0.9.1.6"

 Documentation  Source  Issues

Summary

A RESTful plugin to easily register and associate a webhook with individual controllers (ie services)

Installation

grails install-plugin webhook

Description

This plugin is no longer being maintained. For newer functionality, please see the Grails Api Toolkit

The Webhook plugin provides a RESTful API and web interface for registered user to associate webhooks to services so that upon update, said services can 'push' data to their sites for processing; Webhooks are a new way to provide 'push' behaviour for data to replace polling by clients by storing a URL so that when data is ready, it can be sent to clients who have requested associated data.

For more information on what webhooks are, please visit the following links:

Configuration

After installing the plugin, you should be prompted to run the 'init' script. The script prompt you for a 'package-name' and your Spring-Security User Class name :

ex. grails webhook-init com.yourapp User
NOTE: The Package-name expected is the same package as your Spring Security User Class's Package. Just put it in the same package for now and if you want, you can move it later.
To configure your webhook implementation, you must then go into you config and declare which controllers will have webhooks by declaring them as services. Put the name of each controller into the 'webhook.services' list (do not add 'CONTROLLER' as part of name) :
webhook.services = ['Book','Author']
Also change the authorities to match the ROOT/ADMIN roles in your application:
webhook.authorities = ['ROLE_ROOT','ROLE_ADMIN']
This is important as we want users to be able to ONLY ACCESS THEIR webhooks but allow ADMINISTRATORS to pull a complete list. If you leave this out, users will have 'UNAUTHORIZED ACCESS' to viewing others webhooks

The only other field you are concerned with is 'attempts which sets the number or attempts before 'locking' the webhook

Implementation

To add a webhook to your controller, you merely add the service to your controller:

def webhookService

Then after a successful add/edit/update/delete (or other successful operation), either send the domain instance you wish via the command below:

webhookService.postData('<ControllerName>', <domainInstance>,',<action>')

… or use a Map of data in its place:

webhookService.postData('<ControllerName>', <Map>,',<action>')

Below is an example of it used in an update:

def update = {
    …
    if (!bookInstance.hasErrors() && bookInstance.save(flush: true)) {
        webhookService.postData('Book', bookInstance,'update')
        …
        redirect(action: "show", id: bookInstance.id)
    }else{
        …
    }
}

This will :

  • send the 'service', data and 'action taken' out to all people subscribed in the format specified by them
If you wish to cleanup your domain object prior to sending it out (to remove field data from the domain object), you can first format the domain object into a map using 'formatDomainObject' and then edit the map using the 'processMap' method and send the edited map to the service:
Map book = webhookService.formatDomainObject(bookInstance)
Map bookData = webhookService.processMap(book, ['author':'W Shakespeare','user':null])
webhookService.postData('Book', bookData,'save')

or you can do it manually...

def data = webhookService.formatDomainObject(bookInstance)
def Author = data.find{it.key == "Author"}?.key
data[Author] = W Shakespeare' 
def User = data.find{it.key == "User"}?.key
data.remove(User)
webhookService.postData('Book', data,'update')

Usage

The Grails webhook plugin is a fully RESTful plugin and allows webhooks to be registered to individual users and for each specific service. Services MUST be declared in the config so that registered users can access and register for them. These controllers must then be setup with with one additional line upon successful completion to submit the data to the URL provided.

You can access the interface one of two ways. Either via

  • the provided web interface at http://yourapp/webhook. This provides user a simple web interface to listtheir webhooks and add/edit and delete them
  • REST API (see below)

API

To use the REST api, you can call the api directly or you can use curl and replace 'username' and 'password' in the following command:

curl --data "j_username=<username>&j_password=<password>" http://localhost:8080/springSecurityApp/j_spring_security_check --cookie-jar cookies.txt
Once you have logged in, you can now access the webhook api with the following commands(naturally, once the server is live, replace localhost in the following with your domain or IP):

GET

curl --verbose --request GET http://localhost:8080/api/webhook/JSON/1 --cookie cookies.txt
POST (accepts formats of 'XML' or 'JSON')
curl --verbose --request POST --header "Content-Type: application/json" -d '{url: "http://localhost:8080/",name:"my webhook",service:'node',format:'JSON'}' http://localhost:8080/api/webhook/JSON --cookie cookies.txt
PUT (accepts formats of 'XML' or 'JSON')
curl --verbose --request PUT --header "Content-Type: application/json" -d "{id:4,name:'webhook change',url:'http://localhost:8080/test',service:'node',format:'JSON'}" http://localhost:8080/api/webhook/JSON --cookie cookies.txt
DELETE
curl --verbose --request DELETE http://localhost:8080/api/webhook/none/1 --cookie cookies.txt