Skip to main content

​
Purpose

Webhooks allow you to receive real-time updates about events related to your loan applications. This can help you keep your system in sync with Covered’s platform and provide a better experience for your users. Webhooks events are sparse and for security reasons do not contain any PII or sensitive data. This means you will need to make a separate request to the API to get the full details of the event. For example, if you receive a policy.bound event, you will need to make a request to the GET /v1/policies/{id} endpoint to get the details of the policy.

​
Registration

Reach out to Covered support to register for webhooks. You will need to provide a URL to receive the webhook events and optionally provide basic auth credentials to accompany the request to your endpoint.

​
Handling

When you receive a webhook event, you should respond with a HTTP status code in the range of 200-299(inclusive) to acknowledge receipt of the event. Any other status code will be treated as a failure and Covered will retry the request 6 times a day for the next 14 days.

​
Authentication & Handling

​
Headers

​
Authorization
string
Optional. The username and password registered with Covered support for your webhook endpoint, presented as Basic Authorization header. You can use this to verify the request is coming from Covered.
​
X-Covered-Signature-1
string
Optional. A signature of the request body using HMAC SHA-256 with a client secret provided by Covered support. This can be used to verify the integrity of the request and ensure it has not been tampered with in transit. The signature is calculated as follows:
​
X-Covered-Partner-Id
string
The ID from Covered of the partner that shopped the loan
​
X-Covered-External-Id
string
Optional. The ID provided as externalId when the loan application was created

​
HMAC Verification

1

Load your client secret

Load the client secret provided by Covered support. This is the same secret you use for authenticating API requests.
2

Create a signature

Create a HMAC SHA-256 signature of the request body using the client secret as the key. The signature should be in hexadecimal format.
3

Compare signatures

Compare the signature in the X-Covered-Signature-1 header with the signature you created. To prevent timing attacks, use a constant-time comparison function like timingSafeEqual in Node.js. If they match, the request is valid and you can process the webhook event. If they do not match, reject the request as it may have been tampered with.

​
Example Code

import { createHmac, timingSafeEqual } from 'crypto';

export const createSignature = (content) => {
const coveredClientSecret = process.env.COVERED_CLIENT_SECRET;
const signatureAlgorithm = 'sha256';
const hmac = createHmac(signatureAlgorithm, coveredClientSecret);
const signature = hmac.update(content).digest('hex');
return signature;
};

export const verifyRequest = (req) => {
const coveredSignature = req.headers['x-covered-signature-1'];
const mySignature = createSignature(req.rawBody);
const isMessageFromCovered = timingSafeEqual(
  Buffer.from(coveredSignature),
  Buffer.from(mySignature)
);
return isMessageFromCovered;
};

​
Example Signature

However you implement your signature function, when you run it with:
  • content: 'Hello, from Covered!'
  • client secret: 'Open Sesame' the resulting signature should be:
c5bd4c4eab749a037897b3df74f407e095bef784d65c5077252c31525af6d481

​
Schema

All webhook events follow the same common schema at the top level. Differences between events are in the data object. The following fields are common to all events:
​
id
string
required
The ID of the webhook event. This can be used to deduplicate events.
​
type
string
required
The type of the webhook event, which describes what the type of change that happened.
​
objectType
string
required
The subject of the webhook event, which describes what object the change happened to.
​
occurredAt
string
required
The date and time the event occurred in ISO 8601 format. This can be used to prevent replaying old events by rejecting events that are older than our maximum delivery window, which is currently 14 days.
​
data
object
required
The specific data needed to process and make followup calls for this event, usually consisting of the IDs needed to make the followup calls for additional details.
{
  "id": "1bfa8c6b-521c-4d62-b854-0f9776cad806",
  "type": "loan.shopped",
  "objectType": "loan",
  "occurredAt": "2025-07-07T12:36:43.339Z",
  "data": {
    "loanId": "07af98b6-ebc6-45e8-8e9e-64d2b40cf07a",
    "partnerId": "1088491058",
    "platformId": null,
    "externalId": "8920-5"
  }
}

​
Types

​
Loan

Loan webhooks keep you informed about the status of loan applications that your users shop through the Covered marketplace.

​
Policy

Policy webhooks keep you informed about the status of policies that your users buy through the Covered marketplace.