Webhooks offer a powerful solution for real-time event notifications without the need for constant polling. Instead of continuously querying or waiting for updates, Webhooks allow you to subscribe to specific events and receive relevant payloads at your configured webhook URL. This approach enables a streamlined and responsive workflow integration, allowing you to efficiently respond to events as they occur. By leveraging Webhooks, you can enhance your processing efficiency and ensure timely actions based on event triggers.

When processing Books or Documents, certain tasks can be time-consuming and require thorough completion. To obtain analytics for a Book, all Documents within the Book must undergo complete processing since the analytics rely on the information contained in each Document. It is important to allocate sufficient time for Document processing before proceeding with further steps in the analytics process. The time needed for these tasks may vary depending on the complexity of the Documents, requiring proper monitoring measures.

We offer two options for monitoring the progress of a time-consuming operation:

  1. Regularly check the Book status by polling the endpoint until the desired response is received. This approach is simpler to implement and maintain.
  2. Establish a webhook that will be triggered by Ocrolus once the operation is completed. Webhooks provide a more dependable and accurate method of receiving notifications.

Webhook requests sent by Ocrolus have a timeout of 10 seconds. If a request doesn't finish within this period, it'll be marked as timed out.

We recommend ensuring your webhook handlers return as soon as possible or at least significantly earlier than the timeout. Costly, long-running operations, such as outgoing API requests or other I/O operations, should be avoided or offloaded to background workers.

Benefits of webhook implementation

Webhooks offer several benefits that can enhance your workflow. Firstly, they help optimize resource utilization by saving valuable time, bandwidth, and infrastructure resources that would otherwise be consumed by constant polling. With real-time notifications delivered through Webhooks, you can focus on handling events as they occur instead of making frequent requests.

In terms of security and adherence to standards, Webhooks provide additional advantages. You have the option to authenticate your webhook endpoint, ensuring that only authorized requests are processed. This safeguards your system from unauthorized access and potential exploits by unknown malicious clients or agents. Furthermore, you can implement a whitelist for Ocrolus servers, allowing you to specify and restrict the sources from which you accept Webhooks. This enhances the security of your servers and mitigates risks associated with accepting incoming requests from untrusted sources.

Types of webhooks

When setting up Webhooks, you have two options for configuring them:

  • Account-level: It can be configured at the account level, allowing you to receive notifications for events that occur across your entire account. To learn more about this, see Account-level webhook.
  • Organization-level: It can be configured at the organization level, enabling notifications specific to events within your organization. To learn more about this, see Organization-level webhook.

By offering these two levels of configuration, you have the flexibility to tailor webhook notifications to your desired scope, ensuring that you receive relevant and timely updates based on your specific needs.



You can either opt for Account-level webhook or Organization-level webhook. Opting for both at the same time is not possible.

Feature comparison table

The following table provides a comparison of available features at the organization-level and account-level, along with suggested options. This allows for easy reference and comparison of event features.

Comparison criteriaOrganization-level webhookAccount-level webhookSuggested options
Ease of configuration and managementInstead of having to create multiple Webhooks for a single organization, you now have the option to create a single webhook.
However, you still retain the flexibility to configure multiple Webhooks if needed.
Multiple webhooks need to be created per organization as each account requires the creation of a separate webhook.Organization-level webhook
Webhooks limit per organizationWithin the same organization, you can set up multiple webhooks, each with its own unique set of subscribed events.Creating webhooks that apply to all accounts within an organization is not supported. You will need to manually configure the same outbound URL for each account. Additionally, you can only configure one webhook per account.Organization-level webhook
Self-service configuration capability for WebhooksAvailable in DashboardNot available in DashboardOrganization-level webhook
Webhooks configuration visibilityYou can see the list of configured webhooks in the Dashboard.You cannot see the list of configured webhooks in the Dashboard.Organization-level webhook
Testing Webhooks during initial configurationAvailableNot availableOrganization-level webhook

Events comparison table

The following table provides a comparison of available events at the organization-level and account-level, along with their corresponding webhooks. This allows for easy reference and comparison of event options.

Click here to expand/collapse the table of events for comparison
Organization-level event nameAccount-level event name