How To Run an Extension Microservice

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 webhook 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.

1. Run a local server

Start the webserver on localhost by running the main script, for example:

$ python3 webhook.py

2. Set up a remote URL

If you don't have any remote URL to run your extension on, you can use publicly available proxy service such as ngrok.

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 webhook script is running.

3. Configure your Rossum account

You can use rossum tool to configure a Rossum queue to use the extension. Create a hook object with basic attributes. You can configure it in Rossum UI directly, via API or use the rossum tool:

	 rossum hook create "Python Sample Webhook" --hook-type 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:

	rossum 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.

4. Run the extension in production

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.