Getting started with webhooks

Configuring your Ocrolus account for webhooks allows your API integration to automatically trigger notifications.

What is a webhook? 

Webhooks are triggered from Ocrolus’ system to a client’s system. Figuratively, webhooks are like an email that Ocrolus sends to notify you of activity in your account. The activity could be the creation of a new book or the verification of documents within a book, etc. The webhook endpoint is the person receiving the email who takes actions based upon the specific information it receives. 

Technically, the webhook endpoint is simply more code on your server. The webhook endpoint has an associated URL (e.g., https://example.com/webhooks). The Ocrolus notifications are Event objects. This Event object contains all the relevant information about what just happened, including the type of event and the book data associated with that event.

How does Ocrolus use it? 

In Ocrolus' case, when a client registers a webhook, they register a URL and credentials (optional) to authenticate with their HTTP server that will handle the webhook notification. When Ocrolus wants to send a notification back to the client, Ocrolus will send an HTTP message with contents in the body to the URL that the client registered, and then authenticate, if they provided authentication parameters/credentials.

Example: If PennyMae wants to register a webhook and their URL is http://www.pennymae.com/webhook, Ocrolus will send a message to this URL. If PennyMae provides Ocrolus with a user to authenticate with, the system will authenticate, and then the body sent will contain information on what type of notification PennyMae is registered for. The purpose of the webhook is to notify PennyMae of an event that occurred in Ocrolus’ system. 

Can I configure multiple webhooks to one API account?  

Ocrolus supports one webhook endpoint for each API account. You can set up or update the endpoint associated with your API account by using the Configure Webhook endpoint.

However, you can also create multiple API keys and register each API key to have its own webhook URL.

Is there a list of supported event types?

Yes, you can see a list of event types supported below as well as in the Registering Webhook guide.