Difference between revisions of "Webhooks"
Line 5: | Line 5: | ||
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. | 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. | ||
+ | |||
+ | |||
+ | == Basic Information == | ||
+ | * Name - Unique name used to indentify the Web Hook in the list. This is a mandatory field. | ||
+ | * 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 | ||
+ | |||
+ | |||
+ | == 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 - Choose from XML or JSON | ||
+ | * Post Mode - Choose from Asynchronous, Synchronous, or Synchronous Critical | ||
+ | |||
=== HTTP Protocol Information === | === 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. | 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. | ||
+ | |||
=== Example Integration === | === Example Integration === | ||
An example to reading the JSON payload from a webhook can be found on [https://github.com/hornbill/goWebhookListener GitHub] - The code is avialable for use under the [https://wiki.hornbill.com/index.php/The_Hornbill_Community_License_(HCL) Hornbill Community Licence]. | An example to reading the JSON payload from a webhook can be found on [https://github.com/hornbill/goWebhookListener GitHub] - The code is avialable for use under the [https://wiki.hornbill.com/index.php/The_Hornbill_Community_License_(HCL) Hornbill Community Licence]. | ||
+ | |||
+ | [[Category:Administration]][[Category:Integration]] |
Revision as of 14:23, 8 February 2016
Home > Administration > Instance Settings > Web Hooks
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. This is a very powerful mechanism that enables true, near real-time integration with other business systems.
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.
Basic Information
- Name - Unique name used to indentify the Web Hook in the list. This is a mandatory field.
- 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
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 - Choose from XML or JSON
- Post Mode - Choose from Asynchronous, Synchronous, or Synchronous Critical
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.
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.