Documentation
    {{docApp.userSession.userId}}
    {{docApp.userSession.userName}}
    {{docApp.userSession.email}}
    Issuer : {{docApp.userSession.issuerInstance}}
    Expires : {{new Date(docApp.userSession.validUntil).toLocaleDateString()}}

{{docApp.title}}

{{docApp.description}}

INDEX

Documentation Library

Search for information on Hornbill Documentation.

{{docApp.searchError}}

{{docApp.searchResultFilteredItems.length}} results for "{{docApp.currentResultsSearchText}}" in {{docApp.searchFilterBySpecificBookTitle}}

Have questions about this site?

What is this site?

  • This website is Hornbill's new product documentation website and is currently under development.
  • It is intended that all existing and future public-facing documentation we produce will be available to search, browse and share.
  • Hornbill's current documentation is available at Hornbill Wiki but over time this content will be migrated to this documentation site.
  • Please feel free to have a look around at any time.

Why has Hornbill created this site?

  • Hornbill's products have moved on considerably since we introduced it almost 10 years ago. At the time, the MediaWiki tool was sufficient, but we have outgrown it.
  • Our customers are more enterprise focused and more self-sufficient than ever before, so for 2023 and beyond we have established a new documentation platform and team to drive our documentation initiative forwards.
  • We are aiming to deprecate the use of Hornbill Wiki for most Hornbill related documentation.
  • We want to enable our growing partner network with product resources and information, documentation beyond our Wiki approach is required.
  • We could definitely do with some help, and may even pay for some! If you have domain knowledge and would like to help, please check out our Hornbill Docs Contributor Guide and contact the Hornbill docs team at docs@hornbill.com.

What will this site be good for?

  • Community contribution will be facilitated, encouraged, and most welcome.
  • High quality documentation, will be kept up to date as rapidly as our products evolve.
  • Real-time content search and discovery.
  • Articles organized into books, books into libraries, creating a more natural and logical structure to our documentation.
  • Legacy API documentation and various other documentation sources will all be consolidated into a single unified documentation system.
  • Documentation available in browser as well as printable/viewable as PDF on demand.
  • Personalized documentation experience, allowing dark/light mode, article subscriptions, social media sharing and other useful features.
  • Almost all publicly available documentation on docs.hornbill.com will be open-source and available to fork on GitHub, allowing customers to derive their own custom documentation around Hornbill products should they wish to.

What is the timeline for this site?

  • We have taken the decision to publish and make available early, there is very little content at this time.
  • As and when we have completed/usable documentation, it will be published here.
  • We have a host of additional features we wish to add over time, so please watch this space.
  • We expect most of our existing documentation should be reviewed/migrated to docs.hornbill.com over the coming months.
  • The documentation project will be ongoing, will continue to expand, evolve and improve day-by-day.

{{docApp.libraryHomeViewProduct.title || docApp.libraryHomeViewProduct.id}}

{{docApp.libraryHomeViewProduct.description}}

  1. {{book.title}}

{{group.title || group.id}}

{{group.description}}

  1. {{book.title}}

{{group.title}}

{{book.title}}
More...

Webhooks

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

A webhook is the opposite of an API call, a webhook 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 endpoint 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.

Before You Begin

Basic Information

  • 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 Webhook.
  • Application
    Select the Hornbill application where the event is coming from
  • Event Source
    Select the event
  • Enabled
    Enable or disable this Webhook. This can also be done from the main list of Webhooks
  • Authentication
    If the webhook endpoint you are calling requires authentication then you need to create the required credentials in your KeySafe, then, when configuring you web hood you can select the credentials here.

Web Hook Target

  • URL
    The target URL for the Web Hook. The URL depends on whichever system or platform where you webhook resides.
  • Payload Format
    This defines the format of how you would like the data to be received. This can either be XML or JSON
  • Post Mode
    • Asynchronous
      Call the webhook in the background. If you do not need to act on the response from the webhook being called, this is the recommended mode to ues because any latency or performance issues in the webhook being called will nor be reflected in the Hornbill User Interface.
    • Synchronous
      Use this mode if the webhook you call needs to return a response. If a response code other than 200 is returned from the webhook URL, then the action/api call that originated the event may fail. If there is a non-200 response code, and, if the webhook endpoint returns a response body, and the content-type=text/plain, the response body text will be returned as the error message to the caller that fired the webhook.
    • Synchronous Critical
      This is the same as Synchronous but it also mandatory that the webhook being called returns a 200 success response. If not, then whatever caused this event to be fired will fail and throw an error.

HTTP Protocol Information

Your web hook must 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 user’s display in the response body, the response body should be returned as UTF-8 encoded bytes if non-ascii content is required.

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.

Note

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

Create a Request Bin

After creating your Webhook in Hornbill you can test it using the following steps:

  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 available for use under the Hornbill Community License.