Web-hooks

What is a webhook?

A web-hook is a callback to your application that allows our service to communicate a variety of important events related to coverage, grading, company search etc... and are a more efficient solution than polling to find out when a job has completed.

Currently available web-hook types include:

• Grade Change
• Cover Assessment Completed
• Company Refreshed

How do I receive webhooks?

In order for us to send web-hooks to your application, you will need to create a HTTP web-hook endpoint (url) and define a clientSecret.

Web-hook URL:

• Accepts a POST HTTP request, with following payload body in the request:
  { CoverId = "564200aa-7128-4a26-83a8-cf0201903fcc" }
• Use HTTPS with a TLS version >= 1.2
• Public access allowed or if your firewall requires whitelisting use following IP Addresses: 40.68.208.131

clientSecret:

• This is actually a Bearer token defined in the Authentication section. Whatever clientSecret you provide we will use when sending a web-hook.

Authentication

Web-hooks are authenticated using a customer-defined Bearer as a HTTP header. We recommend this token be unique for each web-hook type and that your application validate the token on each callback.

How you generate the token is up to you, but we recommend using a Base64 encoded string such as a JSON Web Token and to follow these basic guidelines:

• Expiration: If there is an expiration date, we recommend choosing a time interval that allows for issuing a new token at most every 6 months to avoid missing web-hooks.
• LoggedInAs: Our webhooks do not require any access or confirmation of receipt by your application. Limit the scope of the token to the lowest access level for processing.

If you choose not to use a base64 encoded string, the characters in your token can only include:

• Alpha
• Numeric
• "-" / "." / "_" / "~" / "+" / "/"

Authorization: Bearer <token>

Payload

Payload is the term used for the event data we send along with the web-hook.

Each web-hook type includes the relevant payload data to refer to which resource has been affected.

A web-hook's payload is JSON formatted and included as the body of the request.

{
    "confirmationId": "uuid",
    "status": "PENDING"
}

Headers

We provide additional headers in the web-hook including:

• X-APIVersion
• Content-type

X-APIVersion: 3.0
Content-Type: application/json

Retry Policy

If the web-hook is unsuccessful in reaching your web-hook endpoint on the first attempt, we will continue to retry up to ten times using an exponential back-off starting at 30 seconds.