Webhooks

From Hornbill
Revision as of 12:44, 20 September 2019 by Danielr (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Home > Administration > System > Settings > Webhooks Index

Introduction

Web Hooks are a great way to integrate Hornbill with other applications that are accessible over the internet. Web Hooks can send information from Hornbill to another application as soon as a record is updated, rather than relying on scheduled imports or the continually polling for data.

A web hook is the opposite to an API call, a web hook is a call over HTTP from your Hornbill instance to a web endpoint of your choosing. Most application actions on a Hornbill instance can trigger an action-specific event when an action is performed. Hornbill can be configured to call to a web end point passing the action-specific data to the web service being invoked. This is a very powerful mechanism that enables true, near real-time integration with other business systems.

Related Articles


Basic Information

Webhooks are configured via Hornbill Administration in Home > System > Settings > Webhooks

  • Name
Unique name used to identify the Web Hook in the list. This is a mandatory field. No spaces allowed.
  • Description
Enter a description to allow others to understand the use of this particular Web Hook
  • Application
Select the Hornbill application where the event is coming from
  • Event Source
Select the event
  • Enabled
Enable or disable this Web Hook. This can also be done from the main list of Web Hooks
  • Authentication
Create and safely store authentication credentials to access the End Point using Hornbill KeySafe


Web Hook Target

  • URL
The target URL for the Web Hook. This will typically be a php or asp page that you have created
  • Payload Format
This defines the format of how you would like the data to be received. Choose from XML or JSON
  • Post Mode
Asynchronous - Fire and forget. Don't worry about the response
Synchronous - If a response code other than 200 is returned from the webhook URL then the API call will fail. The response body will be returned as the error message if the content type is text/plain.
Synchronous Critical - If there is no response a 200 error is returned from the webhook URL and the API call will fail


HTTP Protocol Information

Your web hook should accept a POST verb with either XML or JSON content as the payload (set by webhook properties). For pre-action hooks such as OnCreate, OnUpdate and OnDelete asyncCritical types it is possible to send an error message from your web hook back to the user's screen. To do this simply respond with a 403 response code, set the Content-type: header to text/plain and the actual text message you want to return to the users display in the response body, the response body should be returned as UTF-8 encoded bytes if non-ascii content is requited.


Testing and Examples

RequestBin Test

The [RequestBin] web site is a third party tool that generates a temporary URL that allows you to collect requests made to it and lets you inspect them in a human-friendly way. Use RequestBin to see what your HTTP client is sending from Hornbill.

Information As RequestBin is a third party tool, Hornbill is not responsible for the availability, quality, security, or any other aspect of this tool


After creating your Web Hook in Hornbill test it using the following steps:

Create a Request Bin

  1. Go to the web site http://requestb.in
  2. Click on the Create a RequestBin button
  3. Copy the Bin URL and save it under the URL field in the Web Hook target section of your Hornbill Webhook configuration.
  4. Create a new Request in Hornbill Service Manager
  5. Refresh the RequestBin page
  6. The information from your request should be visible in the format you configured.


Example Integration

An example to reading the JSON payload from a webhook can be found on GitHub - The code is avialable for use under the Hornbill Community Licence.

Personal tools
Namespaces

Variants
Views
Actions
Navigation
Tools