This page will help you setup your webhooks for asynchronous communication with Invofox

Extracting, completing and validating all the information from a document can take a few seconds. For that reason, we always recommend our customers to use our webhook system and leverage an asynchronous communication with Invofox.

Setup your webhooks

Go to Configuration → Developers and focus on the right side of the screen:

To enable webhooks you will need to configure:

  • The HTTP method you want to be called with. You can choose between POST and PUT.
  • The URL where you will be listening for the events. If you want to use different URLs for different events you can do so by creating different webhook configurations within the same environment.
  • The events you want to listen to. Check out our API reference for the list of all available events.
  • The custom headers you want to receive in the request. We will append this headers to the request, and it's only for your use, Invofox will never use these headers for anything else.
  • The hashing algorithm with which you want to sign the request.
  • The secret you want to use with the hashing algorithm. With the hashing algorithm and the secret (which nobody should know!) you will be able to ascertain the request came from Invofox and protect yourself from DDOS and other cybersecurity threats. You will get the hash in the custom header x-invofox-signature.

How do document batches work?

Invofox is particularly well suited for batch processing. That's because most of our customers process large volumes of documents in very short periods of time with us, and we've dedicated significant resources to be able to guarantee the scalability required to meet this challenge.

Documents uploaded to Invofox in a single request will always be batched together. But you can also explicitly batch documents that you submit in different request. In order to do so you need to:

  • Create a batch and safe the id.
  • Send that same id in the document upload request.
  • Batches will automatically be closed 30 seconds after the reception of the last request. You can also explicitly close the batch using the closeBatch parameter in the document upload request.

Batches are useful if you're only going to launch the business process on your side after all documents in a batch have been processed. By using them, you also lower the number of events you will be receiving.

Webhook payload

Whenever you receive a webhook, you will get a JSON with the following structure:

  • The key type will inform you what kind of event you are receiving. For a full list of supported events, check out our API reference
  • The key data will contain the associated object's (document or batch) information.
  • The key time, which we use to prevent potential capture and replication threats.

Error and retrial policy

By default, Invofox will make up to two retries if an HTTP response code other than 200 is received.

To avoid timeouts, it is recommended to respond with an HTTP 200 code immediately upon receiving the request, without initiating any synchronous tasks.