Ocrolus Webhooks API
The Webhooks API from Ocrolus — 4 operation(s) for webhooks.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/ocrolus-webhooks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Account Level Webhooks API
version: 1.0.0
servers:
- url: https://api.ocrolus.com
security:
- oauth: []
tags:
- name: Webhooks
paths:
/v1/account/settings/update/webhook_endpoint:
post:
summary: Configure webhook
description: 'Set up a webhook for your account so your application can react to Ocrolus events.
---
You can find a list of supported account-level event types and their sample notifications in the Account-level webhook guide.
> 📘
> Your webhook integration should respond to incoming notifications with a status of `200 OK` to indicate that it''s working properly.
> 🚧 We have a better version!
> This product is superseded by Org Level Webhooks, which we recommend for improved functionality and integration.'
operationId: configure-webhook
tags:
- Webhooks
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- webhook_endpoint
- upload
properties:
webhook_endpoint:
type: string
format: url
description: 'The URL of the endpoint that will receive notifications of Ocrolus events. This should be on your own infrastructure, protected from the outside world on a network level. See [here](doc:allowlist-of-ip-addresses) for a list of IP addresses that you can add to your firewall''s allowlist.
The domain will be checked for validity, although the webhook itself won''t be called. We suggest [testing the endpoint](ref:test-webhook) after configuring it.'
event:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/WebhookEventType'
description: 'A comma-separated list of events that will trigger a call to your webhook. To deregister the webhook, provide an empty array.
The event list given in this parameter will replace all existing subscriptions, i.e. providing a single event will subscribe *only* to that event while unsubscribing from the others.
'
example:
webhook_endpoint: https://webhook_endpoint_url.com/example
event:
- book.verified
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonResponse'
- properties:
response:
$ref: '#/components/schemas/WebhookRegistration'
examples:
SuccessfulWebhookRegistration:
$ref: '#/components/examples/SuccessfulWebhookRegistration'
'400':
description: Client Errors
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonResponse'
- properties:
response:
$ref: '#/components/schemas/WebhookRegistration'
examples:
FailedWebhookRegistration:
$ref: '#/components/examples/FailedWebhookRegistration'
/v1/account/settings/webhook_details:
get:
summary: Get webhook configuration
description: 'Retrieve your most recent webhook configuration.
---
Returns the same object as that of the most recent webhook registration.
You can find a list of supported account-level event types and their sample notifications in the Account-level webhook guide.
> 🚧 We have a better version!
> This product is superseded by Org Level Webhooks, which we recommend for improved functionality and integration.'
operationId: webhook-configuration
tags:
- Webhooks
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonResponse'
- properties:
response:
$ref: '#/components/schemas/WebhookRegistration'
examples:
SuccessfulWebhookRegistration:
$ref: '#/components/examples/SuccessfulWebhookRegistration'
/v1/account/settings/test_webhook_endpoint:
get:
summary: Test webhook
description: 'Send a test payload to your configured webhook endpoint.
---
Requests to this endpoint will send a `POST` request with a test payload of the following JSON in the request body:
```json
{
"status": "VERIFICATION_COMPLETE",
"uploaded_doc_pk": 0,
"book_pk": 0
}
```
> 📘
> Your webhook integration should respond to incoming notifications with a status of `200 OK` to indicate that it''s working properly.
If the webhook fails for any reason, the corresponding HTTP status code and message will be provided in the response''s `message` and `code` attributes.
> 🚧 We have a better version!
> This product is superseded by Org Level Webhooks, which we recommend for improved functionality and integration.'
operationId: test-webhook
tags:
- Webhooks
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: 'The configured webhook returned successfully.
'
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonResponse'
- properties:
response:
required:
- message
properties:
resp_code:
type: integer
description: 'The status code that your webhook returned.
'
message:
type: string
description: 'Details about the response that your webhook returned. If the response wasn''t a success, this attribute will contain the reason.
'
examples:
SuccessfulWebhookTest:
$ref: '#/components/examples/SuccessfulWebhookTest'
FailedWebhookTest:
$ref: '#/components/examples/FailedWebhookTest'
callbacks:
WebhookTest:
'{$response.body.webhook_endpoint}':
summary: Webhook Test Event
post:
summary: Webhook Test Payload
description: "A simple test object that approximates the structure of a full webhook payload. The payload will be as follows:\n\n```json\n{\n \"status\": \"VERIFICATION_COMPLETE\",\n \"uploaded_doc_pk\": 0,\n \"book_pk\": 0\n}\n```\n"
responses:
'200':
description: 'Your webhook endpoint should return a status of `200 OK` to indicate that it''s working properly. The content of the response payload doesn''t matter.
'
default:
description: 'If your webhook returns anything besides a 200, the test is considered to have failed.
'
/v1/account/settings/webhook/rotate-secret:
post:
summary: Configure webhook secret
description: 'This API configures the secret key for account-level webhook signature verification. Use this API to add a new secret or update an existing one. The secret is used to sign webhook payloads using HMAC SHA256, allowing you to verify that requests originate from Ocrolus.
> 🚧 We have a better version!
> This product is superseded by Org Level Webhooks, which we recommend for improved functionality and integration.'
operationId: configure-webhook-secret-account-level
tags:
- Webhooks
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- secret_key
properties:
secret_key:
type: string
description: The new webhook secret key. Must be between 16 and 128 characters long.
example: sample_secret_1230ab
required:
- name
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Success
content:
application/json:
schema:
title: Success
type: object
description: Schema for the successful response of new secret key.
properties:
response:
type: object
properties:
status:
type: string
description: Indicates the request status.
message:
type: string
description: Confirmation message.
examples:
Success:
value:
status: success
message: Webhook secret rotated successfully
'404':
description: Webhook Not Found
content:
application/json:
examples:
Webhook not found:
value:
error: Webhook not found
schema:
properties:
status:
type: integer
description: A numerical code that indicates the status of the request.
message:
type: string
description: A textual description that indicates details about this response's status.
components:
examples:
FailedWebhookTest:
summary: Failed Test
value:
status: 200
response:
message: 'Error: Failed to invoke webhook end point 401 Client Error: UNAUTHORIZED for url: https://httpbin.org/status/401'
message: OK
FailedWebhookRegistration:
summary: Failed Registration
value:
status: 400
code: 1806
response: null
message: One of the input is invalid
meta:
status: 400
msg: One of the input is invalid
code: 1806
SuccessfulWebhookTest:
summary: Success
value:
status: 200
response:
resp_code: 200
message: Success calling webhook endpoint
message: OK
SuccessfulWebhookRegistration:
summary: Success
value:
status: 200
response:
webhook_endpoint: https://webhook_endpoint_url.com/example
events:
- DOC_VERIFIED
- BOOK_VERIFIED
message: OK
schemas:
JsonResponse:
type: object
required:
- status
- message
- response
properties:
status:
type: integer
default: 200
description: 'Numerical code indicating the status of this request. Will be 200 for a successful response.
'
code:
type: integer
description: 'Numerical code indicating the nature of an error. Will not be present if the response is successful.
'
message:
type: string
default: OK
description: 'A textual description that indicates details about this response''s status. Will be "OK" for a successful request.
'
WebhookRegistration:
description: 'An object that describes the active webhook registration. Only one webhook can be registered at this time; if you need multiple event handlers, your implementation should inspect the request payload and direct events as needed.
'
required:
- webhook_endpoint
- events
properties:
webhook_endpoint:
type: string
format: url
description: 'The value of `webhook_endpoint` that was provided in the request. Can contain query parameters, port numbers, authentication credentials, and other URL components.
'
events:
type: array
description: 'The webhook events that were successfully registered. Invalid event names will not be included here.
'
minItems: 0
items:
$ref: '#/components/schemas/WebhookEventType'
WebhookEventType:
type: string
description: 'The type of event that Ocrolus broadcasts.
'
enum:
- ANALYTICS_COMPLETED
- book.analytics_v2.generated
- book.classified
- book.completed
- book.detect.signal_found
- book.detect.signal_not_found
- BOOK_VERIFIED
- book.income.generated
- book.income.updated
- document.classification_failed
- document.classification_succeeded
- document.detect.signal_found
- document.detect.signal_not_found
- document.detect.unable_to_process
- document.upload_failed
- document.upload_succeeded
- DOC_VERIFIED
- image_group.upload_failed
- image_group.upload_succeeded
- IMAGE_GROUP_VERIFIED
- mixed_document.rejected
- network.book.created (BETA)
- network.book.funded (BETA)
- plaid.upload_failed
- plaid.upload_succeeded
securitySchemes:
oauth:
type: oauth2
description: 'OAuth 2.0 support via client credentials flow. See [here](doc:using-api-credentials) for usage information.
'
flows:
clientCredentials:
tokenUrl: https://auth.ocrolus.com/oauth/token
scopes: {}