When working with documents in Rossum, there is a great deal of events you or your operators might want to react to in your workflows. In the most typical scenarios you would want to:
- Perform some action when a document changes status according to the document lifecycle. F.e. when the document switches from “Reviewing” to “Postponed” you notify your domain expert to have a look at the document since there seem to be some inconsistencies.
- Fine-tune your exporting process to ERP when document switches to status “exported”
In order to make the process of setting up such an event notification system we have implemented an Extensions page within the Rossum application where you can create a Webhook object that can send an event notification to a web service defined by an URL.
Listing Webhooks
You can access the space for managing the Rossum Webhooks by:
- Clicking on the Settings gear icon
- Navigating to the Extensions tab in the left part of the page
The Extensions page contains a list of Rossum Extensions. Webhooks are the ones that have a triangle-like icon next to its name.
Creating a Webhook
Click on the “Create extension” button in the top right corner of the Extensions page.
Afterwards, you will be presented with a menu where you can define the attributes of the Webhook:
- Name – the name of the Webhook that will be shown in the app
- URL – your remote URL address where the event notifications will be sent
- Events – the type of event notifications that will be sent to the URL
- Shared secret – a “password” that can be used for authenticating your webhook. Authentication is important in order to maintain trust and security in communication between Rossum and your service.
Linking Webhook to a Queue
In order to start receiving the event notifications you have to assign the Webhook to a Queue. In order to accomplish this, follow the steps below:
- Navigate to the Settings page
- Click on the Queue tab
- Select the target Queue in the list
- Find the Extensions tab on the Queue detail
- Click on the “Add extension” button
- Find the Webhook you want to assign to the Queue and click on the “+” icon
Removing the Webhook
If you would like to stop using a specific Webhook on a Queue then you can just navigate to the Extensions tab on a Queue detail as in the section above. There, you can unassign the Webhook from the Queue.
Furthermore, if you would like to remove the Webhook completely, you can:
- Navigate to the Settings page
- Click on the Extensions tab
- Find the target Webhook in the list and click on the “bin” icon on the right of the Webhook item.
Testing a Webhook
In case you are having difficulties understanding the Webhook push notification you can try a simple test:
- Open https://webhook.site/
- Copy the unique URL where your Webhook events will be sent (URL similar to https://webhook.site/ef5c89b0-2117-48e0-9d3e-881384c1fdf6)
- Paste the URL into the Webhook URL and save the changes (Webhook with “Document status changed” event)
- Open a document in To Review tab and postpone the document by clicking on the clock-like icon in the bottom-left part.
- A new notification arrives on the https://webhook.site/
What has just happened? Rossum triggered a document status change event that was sent to a web service running on the https://webhook.site/ URL. The data sent to the URL contain the event type, document ID and other relevant information.
Using Webhook without own web server
Actually, managing your own web service in order to start using Webhook notifications is not necessary. You can use the Rossum Webhook with Zapier instead, where a specific Zap would be triggered when a Rossum event notification arrives.
Currently, we have set up common Zaps that can be used with Rossum in your workflow. However, you can create your own Zaps and tweak the workflow towards your needs.
