From this article you will learn:
- What is a Rossum webhook
- How to display all webhooks
- How to create a webhook
- What are the supported webhook events
- How to assign a webhook to a queue
- How to remove a webhook
- How to test a webhook
- How to use a webhook without your own web server
What is a Rossum webhook
What exactly is a Rossum webhook, and how can using it help you with your workflow?
When working with documents in Rossum, you or your operators might want to react to many events in your workflows. In the most typical scenarios, you would like 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.
Using our extensions page in the Rossum application will allow you to configure such an event notification system. You can create a Webhook object that will send an event notification to a URL-defined web service.
How to display all webhooks
You can access the space for managing the Rossum Webhooks by:
- Clicking on the Extensions tab at the top of the Rossum app.
- Opening the My Extensions tab on the left part of the page.
This page contains a list of Rossum extensions you have enabled. Webhooks are the ones that have a triangle-like icon next to their name.
How to create a webhook
Click on the “Create extension” button in the top right corner of the My extensions page.
Afterward, you will be presented with a menu where you can define the attributes of the webhook:
- Name – the name of the webhook that you will see in the app.
- Description – you can add a description of the webhook for your convenience. It is an optional field.
- Triggered Events – the type of event notifications sent to the URL (described more in the next section).
- Queues – specify on which queues you want the extension to be enabled.
- Extension type – here you should choose “Webhook” option.
- URL – your remote URL address where Rossum will send the event notifications.
- Shared secret – a “password” that Rossum can use for authenticating your webhook. Authentication is essential to maintain trust and security in communication between Rossum and your service.
What are the 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:
- Email – Received
- Filter out non-relevant documents that Rossum should not process.
- Document status – Changed
- Trigger a specific action in your workflow when the document’s status changes.
- Document content – Initialize
- Update the document’s data right when it gets processed by the AI Engine. For example, match the captured vendor name to master data before the user opens the document.
- Document content – User Update
- Show a custom message to the user when they update the field value in the validation screen.
- Document content – Export
- Send the verified data to the ERP/AP system when a user clicks on the “Confirm” button.
Note: If you are looking for more technical information, follow our developer guide.
How to assign a webhook to a queue
The last step before seeing the webhook in production is assigning it to a queue. You can do so while creating a new webhook.
However, later on, you may want to add this new webhook to different queues as well. In such a case, you have two ways to do so.
Assign a webhook using Extensions
It is an efficient way to assign a webhook to multiple queues simultaneously.
- Navigate to the My Extensions tab.
- Click on the webhook you want to assign.
- In the webhook window, choose which queues should have it enabled.
Assign a webhook within the queue
It is useful when you want to add a serverless function to only one specific queue.
- Open the required queue.
- Navigate to the Queue Settings and select Extensions.
- Choose the “Attach extension” option.
- Select the webhook you want to enable on that queue.
How to remove a webhook
Suppose you would like to stop using a specific webhook on a queue. In that case, navigate to the My 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 delete the Webhook, you can:
- Navigate to the Settings page.
- Click on the My Extensions tab.
- Find the target webhook on the list and click on the “bin” icon on the right of the webhook item.
How to test 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 the To Review tab and postpone the document by clicking on the clock-like icon in the bottom-left part.
- A new notification arrives on https://webhook.site/.
What has just happened? Rossum triggered a document status change event sent to a web service running on https://webhook.site/. The data sent to the URL contain the event type, document ID, and other relevant information.
How to use a webhook without your own web server
Managing your web service to start using webhook notifications is unnecessary. You can use the Custom Function or Rossum webhook with Zapier, where a specific Zap would be triggered when a Rossum event notification arrives.
We have set up common Zaps that you can use with Rossum in your workflow. Also, you can create your Zaps and tweak the workflow to suit your needs.
