When working with documents in Rossum, there are 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:
- Show a custom message to the user in the validation screen
- Compute missing values in a document based on captured data
- Postpone a document and notify your domain expert to have a look at the document if there seem to be some inconsistencies
- Fine-tune your exporting process to your ERP when a document is confirmed.
To enable you to set 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 (described more in the next section).
- 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.
Supported Webhook events
Whenever a specific event happens in the Rossum app, a notification is sent to the defined URL, representing your web service. Based on the type of event, a response could be returned back to the user and shown in the Rossum validation screen, or the service running on the URL could process the message without any response to Rossum.
Below is the list of currently supported events and use cases they might be used for:
- Document status changed
- trigger a specific action in your workflow when document’s status changed.
- Document content is being initialized
- update the document’s data right when it got processed by the AI Engine. For example, match the captured vendor name to master data before the user opens the document.
- Document content is being updated
- show a custom message to the user in the validation screen.
- Document content is being exported
- send the verified data to the ERP/AP system when a user clicks on the “Confirm” button.
Linking Webhook to a queue
In order to start receiving the event notifications you have to assign the Webhook to a queue. 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, 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 your 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 to suit your specific needs.
