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 5 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:

• Organization-level: It can be configured at the organization level, enabling notifications specific to events within your organization. This webhook is available in the Ocrolus Dashboard, and it is strongly recommended that you utilize this specific webhook type for its ease of use and seamless integration. To learn more about this, see Organization-level webhook.
• 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.

📘

Note

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.

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 name	Account-level event name
book.analytics_completed	ANALYTICS_COMPLETED
book.analytics_v2.generated	book.analytics_v2.generated
book.classified	book.classified
book.completed	book.completed
book.detect.signal_found	book.detect.signal_found
book.detect.signal_not_found	book.detect.signal_not_found
book.verified	BOOK_VERIFIED
book.income.generated	book.income.generated
book.income.updated	book.income.updated
document.classification_failed	document.classification_failed
document.classification_succeeded	document.classification_succeeded
document.detect.signal_found	document.detect.signal_found
document.detect.signal_not_found	document.detect.signal_not_found
document.detect.unable_to_process	document.detect.unable_to_process
document.upload_failed	document.upload_failed
document.upload_succeeded	document.upload_succeeded
document.verification_failed	DOC_VERIFIED
document.verification_succeeded	DOC_VERIFIED
image_group.upload_failed	image_group.upload_failed
image_group.upload_succeeded	image_group.upload_succeeded
image_group.verification_failed	IMAGE_GROUP_VERIFIED
image_group.verification_succeeded	IMAGE_GROUP_VERIFIED
plaid.upload_failed	plaid.upload_failed
plaid.upload_succeeded	plaid.upload_succeeded
network.book.created	network.book.created
network.book.funded	network.book.funded