Rossum Developer Hub

Rossum Data Capture for Developers and Integrators

Welcome to the Rossum developer hub. You'll find comprehensive guides and documentation to help you implement Rossum as quickly as possible, as well as support if you get stuck.

Let's jump right in!

Developer Guides    API Reference    User Help Center    Feature wishlist

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

1. Run a local server

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

$ python3

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 services such as ngrok or serveo.

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

3. Configure your Rossum account

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.

3a. Configure Your Webhook Extension

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

3b. Configure Your Connector Extension

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 - authorization_token and service_url.

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.

The service_url is your remote URL where the connector is running. In this example, it is the tunnel.


Query parameters in URL

If the service URL of the connector contains query parameters, you should pass them via params attribute of a connector object. Passing them directly in the service_url parameter 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.

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.

Updated 7 months ago

How To Run an Extension Microservice

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.