Using an extension, you can do many extra activities that Rossum application does not do by default, such as cross-checking sums, pairing extracted data against your database or modifying the export data to meet the needs of your external ERP system. We have published a few sample extensions on the Rossum GitHub that can help you to understand the implementation structure and functional possibilities of the webhook and connector extensions.
This article will provide you with information on how to set up and run your first microservice that implements the webhook API. To try out the workflow on an example, you can use our Sample Python Webhook.
Start the webserver on localhost by running the main script, for example:
$ python3 webhook.py
Expose a web server on a port of your local machine to the internet, for example:
$ ngrok http 5042
A new tunnel produced by ngrok will be created with URL such as
https://123456e7.ngrok.io. You will use this address in the following step as the URL of your extension.
Like this, every time a request will be sent from Rossum to your extension, it will be tunneled to the port 5042 on your localhost. You can test if the requests are tunneled correctly by typing the new URL to your browser and see if your request was displayed correctly in the command line where your main connector script is running.
You can use rossumctl tool to configure a Rossum queue to use the extension. Depending on what kind of extension you use, refer to one of the sections below to configure your Rossum account correctly.
Create a hook object with basic attributes. You can configure it in Rossum UI directly, via API or use the rossumctl tool:
rossumctl webhook create "Python Sample Webhook" --active true -e annotation_content.initialize -e annotation_content.user_update --config-url https://yourremoteurl.com/vendor_matching -q QUEUE_ID --config-secret YOUR_SECRET_HERE
YOUR_SECRET_HERE is a secret key that Rossum uses to create a hash signature with each payload. You will validate this secret in the webhook (within the hmac_signature_required() function in webhook.py) to check that the request was sent by Rossum.
To configure the schema for webhook to work:
rossumctl queue change SCHEMA_ID -s example_schema.json
SCHEMA_ID is an id of the schema that the webhook should be run on.
example_schema.json = example schema that is set up to work with webhook. Can be customized based on your needs.
Create a connector object with basic attributes:
rossumctl connector create "Python Example Connector" --service-url http://hostname:5000 --auth-token wuNg0OenyaeK4eenOovi7aiF
There are two attributes that you should always assign to the connector -
The authorization token is a secret combination chosen by yourself, passed in an Authorization HTTP header as
Authorization: secret_key your_auth_token_here
This token may also uniquely identify the organization when multiple Rossum organizations share the connector running on the same URL.
service_url is your remote URL where the connector is running. In this example, it is the
Query parameters in URL
If the service URL of the connector contains query parameters, you should pass them via
paramsattribute of a connector object. Passing them directly in the
service_urlparameter would not work.
In the response from rossumctl, you will receive the ID of the connector. Next, choose an existing queue and deploy the connector to it:
rossumctl queue change 29582 --connector-id 1506
Or create a new queue and attach the connector to it:
rossumctl queue create "Python Connector Queue" --connector-id 1506 -s schema.json
You can also configure the connector using API.
To use the extension for production, try to follow our best practices. The extension should:
- communicate securely by running via HTTPS with a valid public certificate (using, for example, Nginx proxy with Let's encrypt TLS/SSL certificate);
- authenticate the caller to prevent impersonation by another party, by requiring Rossum side to authenticate using an authentication secret;
- do not restrict the source IP address as that may change over time;
- be fast enough to keep up the pace with Rossum interactive behavior.
For more detailed information on extensions see our API documentation.
Updated about a month ago