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. Web-hooks are a more efficient solution than polling to find out when a job has completed.

Currently available web-hook types include:

• Grade Change
• Cover Status Update
• Cover Assessment Completed

How do I receive webhooks?

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

Web-hook URL

• Accepts a POST HTTP request with the following payload body:
  JSON

  { "CoverId": "564200aa-7128-4a26-83a8-cf0201903fcc" }
  

• Use HTTPS with a TLS version >= 1.2.
• Ensure public access or whitelist the following IP Addresses in your firewall: 108.141.248.216, 13.95.149.245, 13.95.144.211, 13.95.148.210, 3.95.144.114, 40.68.208.131.

Client Secret

• This is a Bearer token defined in the Authentication section. The token you provide will be used when sending a web-hook.

Authentication

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

Guidelines for the token:

• Expiration: Consider a time interval allowing renewal every six months to avoid missing web-hooks.
• Scope: Limit the scope of the token to the lowest access level necessary for processing.

If not using a Base64 encoded string, allowed characters for the token are:

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

Headers  
Authorization: Bearer <token>

Payload

The payload contains the event data sent with the web-hook. Each web-hook type includes the relevant payload data about the affected resource.

Payloads are JSON-formatted and included as the request body.

Payload Example

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

Headers

Additional headers included in the web-hook:

• X-APIVersion: Current API version (e.g., 3.0).
• Content-Type: Always set to application/json.

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

Retry Policy

If a web-hook fails to reach your endpoint, we retry up to 10 times using an exponential backoff starting at 30 seconds.

Subscribe to Webhooks

Subscribe to an Event

To subscribe to the COVER_STATUS_CHANGED event (for example), send a POST request to the /v3/settings/webhooks endpoint with the following details:

Request

POST /v3/settings/webhooks HTTP/1.1
Host: {{root-url}}
Content-Type: application/json
apikey: {{coverage-api-key}}

{
    "eventType": "COVER_STATUS_CHANGED",
    "callbackUrl": "{{webhook-url}}",
    "httpVerb": "POST",
    "authorizationHeaderName": "{{header-name}}",
    "authorizationHeaderValue": "{{header-value}}"
}

Expected response: 200 OK

Get Subscribed Events

To retrieve a list of your current web-hook subscriptions, send a GET request to the /v3/settings/webhooks endpoint.

Request

GET /v3/settings/webhooks HTTP/1.1
Host: {{root-url}}
apikey: {{coverage-api-key}}

Expected response: 200 OK

Response Example

[
    {
        "eventType": "COVER_STATUS_CHANGED",
        "callbackUrl": "https://webhook.site/example",
        "httpVerb": "POST",
        "authorizationHeaderName": "Authorization",
        "authorizationHeaderValue": "123"
    }
]

Update a Subscription

To update an existing subscription, send a PUT request to the same /v3/settings/webhooks endpoint. Use the same payload structure as when creating a subscription.

Verifying Webhook Signatures

To enhance security, we include an additional HTTP header: ATP-SIGNATURE. This header contains an HMAC hash of the web-hook payload.

Generating the Secret Key

To generate a secret key, send a POST request to the /v3/settings/secret endpoint:

Request

POST /v3/settings/secret?version=3 HTTP/1.1
Host: {{root-url}}
Content-Type: application/json
apikey: {{coverage-api-key}}

Response

{
    "secret": "<value>"
}

Example: Verifying the Signature

You can use the generated secret key to verify the HMAC signature in the ATP-SIGNATURE header. Here's an example in PHP:

$payload = '{payload}';
$secret = '{secret}';
$hash_mac = hash_hmac('sha256', $payload, $secret);

Make sure to verify that the calculated hash matches the value in the ATP-SIGNATURE header before processing the payload.