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:

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

     JSON example

     {
       "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",  
     }
     

2. book.analytics_v2.generated: This event signifies the analytics data for a Book is generated using the v2 analytics engine.

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

     JSON example

     {  
       "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"  
     }
     

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

     JSON example

     {
       "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"
     }
     

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

     JSON example

     {
       "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"
     }
     

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

     JSON example

     {
       "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"
     }
     

6. BOOK_VERIFIED: Indicates that all documents within a book have been verified or rejected. This event corresponds to the BOOK_COMPLETE status returned by the Book status. To learn more about various book statuses, see Book Status endpoint.

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

     JSON example

     {
       "status": "BOOK_COMPLETE",
       "event_name": "BOOK_VERIFIED",
       "book_pk": 11917,
       "book_uuid": "35ef4501-b93d-4ce2-b766-b670a057c0fb"
     }
     

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

     JSON example

     {
       "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"
     }
     

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

  JSON example

  {
    "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"
  }
  

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

  JSON example

  {
    "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 document",
    "mixed_uploaded_doc_pk": null,
    "mixed_uploaded_doc_uuid": null,
    "uploaded_image_group_pk": null,
    "uploaded_image_group_uuid": null
  }
  

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

      JSON example

      {
        "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
      }
      

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

      JSON example

      {
        "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
      }
      

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

      JSON example

      {
        "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"
      }
      

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

      JSON example

      {
        "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"
      }
      

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

      JSON example

      {
        "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

      JSON example

      {
        "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"
      }
      

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

      JSON example

      {
        "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"
      }
      

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

      JSON example

      {
        "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"
      }
      

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

      JSON example

      {
        "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

      JSON example

      {
        "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",
      }
      

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

      JSON example

      {
        "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"
      }
      

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

      JSON example

      {
        "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"
      }
      

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

      1. • 
           

      JSON example

      {
        "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"
      }
      

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

      1. • 
           

      JSON example

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

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.