Account-level webhooks are personalized notifications for your account. Ocrolus offers a tailored notification system by allowing you to set up a single webhook configuration for a specific account, whether it's a Web User or API credentials.

With this webhook type, you can configure webhooks to be triggered for each API account within your organization that has the webhook feature enabled. It implies that you will receive webhook notifications only for the books that you have created or for which you are the account owner.

In practical terms, when you create a book, you will be the designated recipient of the relevant payload via the configured webhook URL. This ensures that the account associated with the book creation receives personalized notifications about the specific events related to their created books.

By utilizing this webhook type, you can stay informed about the progress and updates of your own books, enabling a more targeted and efficient workflow. This personalized approach enhances the management and monitoring of your account-specific activities within the context of webhook notifications.

Currently, each API account allows for the configuration of one webhook. You can set up a webhook using the Configure Webhook endpoint.

📘
Note
You can create only one webhook per account.

While creating a webhook, you need to provide the following two parameters:

Endpoint URL: This is the address of your webhook endpoint, which must be accessible to Ocrolus. Typically, it is hosted within your own infrastructure, and it is recommended not to make it publicly available on the Internet. To learn more, see Secure webhook URLs.
Subscribed events: Specify the important lifecycle events that will activate notifications for your endpoint as this parameter.

Example

Let's say you are the Data Analyst working at XYZ Corp. As part of your job, you frequently upload documents for analysis using Ocrolus. With the account-level webhook feature, you can set up a personalized notification system for your account.

Now, imagine you create a book called Quarterly Financial Reports and upload multiple documents related to financial statements. Once the book is created, you set up a webhook configuration for your account.

Whenever there is an update or event related to the processing of the Quarterly Financial Reports book, such as the completion of analysis or any errors encountered, you will receive real-time webhook notifications. These notifications will be sent to your designated webhook URL, ensuring that you are promptly informed about the specific events associated with your created book.

For instance, let's say one of the uploaded documents in the book fails to process due to formatting issues. With the account level webhook, you will receive a notification stating the details of the failed document and the reason for the failure. This allows you to identify and resolve the formatting issue quickly, ensuring smooth progress in the analysis of your financial reports.

Available events

The account-level webhooks support the following events:

book.analytics_v2.generated: This event indicates that the analytics data for a Book is produced using the v2 analytics engine. Verified Docs include only those documents that are in the VERIFICATION_COMPLETE state.

Click to expand or collapse the JSON code example of this event

{
  "severity": "HIGH",
  "notification_type": "STATUS",
  "notification_reason": "Analytics V2 generated for the book",
  "event_name": "book.analytics_v2.generated",
  "book_uuid": "8ef7a1e1-fc97-42f9-81ea-ef357b333117",
  "verified_docs": [
    "c5d3a53b-2840-4e9c-8d84-d804e3b17bab"
  ]
}

book.classified: This event indicates that a book has been classified or categorized.

Click to expand or collapse the JSON code example of this event

{
  "notification_type": "STATUS",
  "notification_reason": "Book is classified",
  "mixed_uploaded_docs": [
    {
      "status": "COMPLETED",
      "mixed_uploaded_doc_uuid": "db7fe37f-3fc8-4a0a-9066-94101a174832"
    }
  ],
  "severity": "MODERATE",
  "book_uuid": "8ef7a1e1-fc97-42f9-81ea-ef357b333117",
  "event_name": "book.classified"
}

book.completed: This event is triggered when the Capture, Detect, and Analytics processes are completed for a Book. Capture is mandatory for this event to be triggered, while Analytics and Detect are required only if they are enabled for your organization.

Click to expand or collapse the JSON code example of this event

{
    "tasks": [
        "DETECT",
        "ANALYTICS",
        "CAPTURE"
    ],
    "notification_reason": "Book is Completed",
    "book_uuid": "0742a2a7-8046-4c6f-a23e-ba259ef8e14f",
    "uploaded_docs": [
        {
            "status": "VERIFICATION_COMPLETE",
            "uuid": "6e2151c0-70ee-4454-a09d-585a3277954b"
        }
    ],
    "event_name": "book.completed",
    "notification_type": "STATUS",
    "severity": "HIGH",
    "book_context_class": "INSTANT"
}

📘
Note
The turnaround time (TAT) for this event is the slowest of all the three processes i.e., Capture, Detect, and Analytics.

book.detect.signal_found: Indicates that the uploaded Book contains at least one document that contains signals of suspicious activity.

Click to expand or collapse the JSON code example of this event

{
  "notification_type": "STATUS",
  "notification_reason": "Detect signals found in the book",
  "uploaded_docs": [
      {
          "uploaded_doc_uuid": "db7fe37f-3fc8-4a0a-9066-94101a174832",
          "uploaded_doc_detect_status": "COMPLETED",
          "signal_count": 1,
      },
      {
          "uploaded_doc_uuid": "db7fe37f-3fc8-4a0a-9066-94101a174832",
          "uploaded_doc_detect_status": "UNSUPPORTED",
          "signal_count": 0,
          "reason": "Detect could not find any forms in the document to run on."
      }
  ],
  "severity": "MODERATE",
  "book_uuid": "8ef7a1e1-fc97-42f9-81ea-ef357b333117",
  "event_name": "book.detect.signal_found"
}

book.detect.signal_not_found: Indicates that the uploaded Book does not contain any documents with signals of suspicious activity.

Click to expand or collapse the JSON code example of this event

{
  "notification_type": "STATUS",
  "notification_reason": "Detect signals not found in the book",
  "uploaded_docs": [
      {
          "uploaded_doc_uuid": "db7fe37f-3fc8-4a0a-9066-94101a174832",
          "uploaded_doc_detect_status": "COMPLETED",
          "signal_count": 0,
      }
  ],
  "severity": "MODERATE",
  "book_uuid": "8ef7a1e1-fc97-42f9-81ea-ef357b333117",
  "event_name": "book.detect.signal_not_found"
}

BOOK_VERIFIED: Indicates that the Capture process has been completed, and all documents within a Book have either been verified or rejected.
- Click to expand or collapse the JSON code example of this event
  { "status": "BOOK_COMPLETE", "event_name": "BOOK_VERIFIED", "book_pk": 11917, "book_uuid": "35ef4501-b93d-4ce2-b766-b670a057c0fb" }

document.classification_failed: This event indicates that the classification process for a document has failed.

Click to expand or collapse the JSON code example of this event

{
  "event_name": "document.classification_failed",
  "book_uuid": "8ef7a1e1-fc97-42f9-81ea-ef357b333117",
  "notification_type": "ISSUE",
  "severity": "MODERATE",
  "notification_reason": "File is corrupt",
  "uploaded_image_group_uuid": "c44b1d25-fdbe-488c-b0af-ae062286a67d",
  "mixed_uploaded_doc_uuid": "3ea1bdd6-51e0-4ac5-bee3-e09ca1b683d6"
}

document.classification_succeeded: This event indicates that the classification process for a document has succeeded.

Click to expand or collapse the JSON code example of this event

{
  "book_uuid": "8ef7a1e1-fc97-42f9-81ea-ef357b333117",
  "severity": "MODERATE",
  "notification_reason": "Document is classified",
  "event_name": "document.classification_succeeded",
  "mixed_uploaded_doc_uuid": "3ea1bdd6-51e0-4ac5-bee3-e09ca1b683d6",
  "uploaded_image_group_uuid": "c44b1d25-fdbe-488c-b0af-ae062286a67d",
  "notification_type": "STATUS"
}

document.detect.signal_found: Indicates that the uploaded document contains signals of suspicious activity.

Click to expand or collapse the JSON code example of this event

{  
  "status": "VERIFICATION_COMPLETE",  
  "book_pk": 103760,  
  "severity": "LOW",  
  "book_name": "test-notification",  
  "book_uuid": "5a9f2eed-7de7-4d6a-ab8a-28d0e91bf680",  
  "event_name": "document.detect.signal_found",  
  "uploaded_doc_pk": 1434677,  
  "notification_type": "STATUS",  
  "uploaded_doc_name": "sample bankstatement.pdf",  
  "uploaded_doc_uuid": "63231617-d558-4838-ab4c-699b392f0c17",  
  "is_cloud_compliant": false,  
  "notification_reason": "Detect signals found in the document",  
  "mixed_uploaded_doc_pk": null,  
  "mixed_uploaded_doc_uuid": null,  
  "uploaded_image_group_pk": null,  
  "uploaded_image_group_uuid": null  
}

document.detect.signal_not_found: Indicates that the uploaded document does not contain signals of suspicious activity.

Click to expand or collapse the JSON code example of this event

{
  "status": "VERIFICATION_COMPLETE",
  "book_pk": 103760,
  "severity": "LOW",
  "book_name": "test-notification",
  "book_uuid": "5a9f2eed-7de7-4d6a-ab8a-28d0e91bf680",
  "event_name": "document.detect.signal_not_found",
  "uploaded_doc_pk": 1434677,
  "notification_type": "STATUS",
  "uploaded_doc_name": "sample bankstatement.pdf",
  "uploaded_doc_uuid": "63231617-d558-4838-ab4c-699b392f0c17",
  "is_cloud_compliant": false,
  "notification_reason": "No detect signals found in document",
  "mixed_uploaded_doc_pk": null,
  "mixed_uploaded_doc_uuid": null,
  "uploaded_image_group_pk": null,
  "uploaded_image_group_uuid": null
}

document.detect.unable_to_process: Indicates that the uploaded document could not be processed through Detect. The specific reason for this will be provided in the webhook.

Click to expand or collapse the JSON code example of this event

{
  "status":"VERIFICATION_COMPLETE",
  "book_pk":103760,
  "severity":"LOW",
  "book_name":"test-notification",
  "book_uuid":"5a9f2eed-7de7-4d6a-ab8a-28d0e91bf680",
  "event_name":"document.detect.unable_to_process",
  "uploaded_doc_pk":1434677,
  "notification_type":"STATUS",
  "uploaded_doc_name":"sample bankstatement.pdf",
  "uploaded_doc_uuid":"63231617-d558-4838-ab4c-699b392f0c17",
  "is_cloud_compliant":false,
  "notification_reason":"Detect couldn't process the document. Reason: Currently, Detect does not support image based PDFs.",
  "mixed_uploaded_doc_pk":null,
  "mixed_uploaded_doc_uuid":null,
  "uploaded_image_group_pk":null,
  "uploaded_image_group_uuid":null
}

document.upload_failed: This event indicates that the upload of a document has failed.

Click to expand or collapse the JSON code example of this event

{
  "severity": "MODERATE",
  "notification_reason": "File is corrupt",
  "notification_type": "ISSUE",
  "event_name": "document.upload_failed",
  "file_name": "test_file.pdf",
  "book_uuid": "8ef7a1e1-fc97-42f9-81ea-ef357b333117"
}

document.upload_succeeded: This event indicates that the upload of a document has succeeded.

Click to expand or collapse the JSON code example of this event

{
  "notification_type": "STATUS",
  "notification_reason": "Document uploaded",
  "book_uuid": "8ef7a1e1-fc97-42f9-81ea-ef357b333117",
  "event_name": "document.upload_succeeded",
  "doc_uuid": "db7fe37f-3fc8-4a0a-9066-94101a174832",
  "severity": "LOW"
}

DOC_VERIFIED: Indicates that a single document within a book has been verified or rejected. This event corresponds to the document statusVERIFICATION_COMPLETE and REJECTED. For more information about document statuses, see Document statuses.

Click to expand or collapse the JSON code example of doc verification succeeded event

{
  "status": "VERIFICATION_COMPLETE", 
  "book_pk": 6777219, 
  "book_uuid":   "0d8bb103-643c-4620-ace9-e042ec2e93b8",
  "uploaded_doc_pk": 13027406,
  "uploaded_doc_uuid": "7491a1b5-4edd-4fa8-9ed5-9a7ab2744127", 
  "mixed_uploaded_doc_pk": null,
  "mixed_uploaded_doc_uuid": null, 
  "uploaded_image_group_pk": null, 
  "uploaded_image_group_uuid": null,
  "event_name": "DOC_VERIFIED"
}

Click to expand or collapse the JSON code example of doc verification failed event

{
  "status": "REJECTED", 
  "book_pk": 6622008,
  "book_uuid": "446ceb3b-8c2a-45c0-82a8-0b21640c86f6", 
  "uploaded_doc_pk": 12856201, 
  "uploaded_doc_uuid": "b0bf0eb7-c1fd-4473-aba3-ea93dd619a22",
  "mixed_uploaded_doc_pk": null, 
  "mixed_uploaded_doc_uuid": null, 
  "uploaded_image_group_pk": 2515686, 
  "uploaded_image_group_uuid": "37b53b86-3d83-4c1a-86aa-e22bd522720c",
  "event_name": "DOC_VERIFIED"
}

image_group.upload_failed: This event indicates that the upload of an image group has failed.

Click to expand or collapse the JSON code example of this event

{
  "book_uuid": "8ef7a1e1-fc97-42f9-81ea-ef357b333117",
  "event_name": "image_group.upload_failed",
  "notification_reason": "File is corrupt",
  "image_group_uuid": "db7fe37f-3fc8-4a0a-9066-94101a174832",
  "notification_type": "ISSUE",
  "severity": "MODERATE"
}

image_group.upload_succeeded: This event indicates that the upload of an image group has succeeded.

Click to expand or collapse the JSON code example of this event

{
  "event_name": "image_group.upload_succeeded",
  "severity": "MODERATE",
  "notification_reason": "Image group is uploaded",
  "notification_type": "STATUS",
  "book_uuid": "8ef7a1e1-fc97-42f9-81ea-ef357b333117",
  "image_group_uuid": "db7fe37f-3fc8-4a0a-9066-94101a174832"
}

IMAGE_GROUP_VERIFIED: This event is triggered in both scenarios, namely when the image group verification fails and when it succeeds. However, no event is triggered specifically for the status update of theREJECTED. To learn more about image grouping, see Image group.

Click to expand or collapse the JSON code example of image group verification failed event

{
  "status": "COMPLETED", 
  "book_pk": 6638269, 
  "book_uuid": "6ed803d7-6cd2-485f-b8b1-088c03362df2",
  "uploaded_image_group_pk": 2512560, 
  "uploaded_image_group_uuid": "93850c56b69f-4f3b-a8ee-e9acac0a9bad",
  "event_name": "IMAGE_GROUP_VERIFIED",
}

Click to expand or collapse the JSON code example of image group verification succeeded event

{
  "status": "COMPLETED", 
  "book_pk": 6638269, 
  "book_uuid": "6ed803d7-6cd2-485f-b8b1-088c03362df2",
  "uploaded_image_group_pk": 2512560, 
  "uploaded_image_group_uuid": "93850c56b69f-4f3b-a8ee-e9acac0a9bad",
  "event_name": "IMAGE_GROUP_VERIFIED",
}

plaid.upload_failed: This event indicates that the upload of Plaid data has failed.

Click to expand or collapse the JSON code example of this event

{
  "notification_type": "ISSUE",
  "book_uuid": "8ef7a1e1-fc97-42f9-81ea-ef357b333117",
  "file_name": "test_file.json",
  "notification_reason": "File is corrupt",
  "event_name": "plaid.upload_failed",
  "severity": "MODERATE"
}

plaid.upload_succeeded: This event indicates that the upload of Plaid data has succeeded.

Click to expand or collapse the JSON code example of this event

{
  "notification_reason": "Json uploaded",
  "severity": "LOW",
  "notification_type": "STATUS",
  "doc_uuid": "db7fe37f-3fc8-4a0a-9066-94101a174832",
  "event_name": "plaid.upload_succeeded",
  "book_uuid": "8ef7a1e1-fc97-42f9-81ea-ef357b333117"
}

network.book.created (BETA): Indicates that another Network customer submitted an application for a borrower you are currently monitoring (SMB only).

Click to expand or collapse the JSON code example of this event

{
  "notification_type": "STATUS",
  "notification_reason": "A new application has been submitted for a borrower you are currently monitoring",
  "severity": "HIGH",
  "book_uuid": "8ef7a1e1-fc97-42f9-81ea-ef357b333117",
  "event_name": "network.book.created"
}

network.book.funded (BETA): Indicates that another Network customer funded a borrower you are currently reviewing or monitoring (SMB only).
- Click to expand or collapse the JSON code example of this event
  { "severity": "HIGH", "notification_type": "STATUS", "notification_reason": "A borrower you are currently reviewing or monitoring has been funded", "event_name": "network.book.funded", "book_uuid": "8ef7a1e1-fc97-42f9-81ea-ef357b333117"
  📘
  Note
  The SUSPICIOUS_ACTIVITY event is only relevant for email notifications and does not apply to webhook notifications.
ANALYTICS_COMPLETED: Indicates the completion of an asynchronous analytics request, making the results accessible. To learn more about this, see Async analytics request.
- Click to expand or collapse the JSON code example of this event
  { "event": "ANALYTICS_COMPLETED", "status": "COMPLETED", "book_pk": 11917, "analytics_request_id": "419bcd3f-dba5-43a1-88b0-9bf0adebd332", "book_uuid": "bf4cbe64-3ff3-4e68-9234-452aa7c7a6de", "event_name": "ANALYTICS_COMPLETED", }
  📘
  Note
  This event is only for our Legacy Analytics offering.

Configure account-level webhook

To configure and manage account-level webhooks, you can utilize our webhook endpoints. For detailed information on how to set up the configuration, see the WEBHOOK section in our API ref documentation.

📘Note

Example

Available events

📘Note

📘Note

📘Note

Configure account-level webhook

📘
Note

📘
Note

📘
Note

📘
Note