Web Hooks

Our API will publish the following events to registered webhooks. All webhook requests are sent via POST and include a VerticalInsure-Signature header which is an HMAC-SHA256 and can be used to validate the request came from Vertical Insure. The header value is a hash of the webhook's signature_key and the json request body.

Subscribing to Web Hook Events

To create a webhook and subscribe the webhook to certain events, login to our Partner Portal and navigate to the Webhooks page.

Generating Signatures for Validation

Java

Mac mac = HmacUtils.getInitializedMac(HmacAlgorithms.HMAC_SHA_256,
            signatureKey.getBytes(StandardCharsets.UTF_8));
String signature = Hex.encodeHexString(mac.doFinal(eventJson.getBytes(StandardCharsets.UTF_8)));

Python

import hmac
import hashlib

signature = hmac.new(
    bytes(signature_key , 'utf-8'),
    msg = bytes(event_json , 'utf-8'),
    digestmod = hashlib.sha256
).hexdigest().upper()

Ruby

digest = OpenSSL::Digest.new('sha256')
signature = OpenSSL::HMAC.hexdigest(digest, signature_key, event_json)

PHP

$requestBody = file_get_contents('php://input');
$signature = hash_hmac('sha256', $requestBody, $signature_key);

Policy Events

policy_bind_complete

Sent once the policy bind process has been completed.

{
    'event': 'policy_bind_complete',
    'webhook': 'https://www.example.com/my-webhook',
    'data': {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "master_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "policy_number": "string",
        "customer": {
            "first_name": "string",
            "last_name": "string",
            "email_address": "string"
        },
        "policy_status": "ACTIVE",
        "issued_date": "2022-09-05",
        "expiration_date": "2022-09-05",
        "effective_date": "2022-09-05",
        "quote_date": "2022-09-05",
        "policy_attributes": {},
        "premium_amount": 0,
        "quote_id": "string",
        "is_test": true
    }
}

policy_bind_failed

Sent once the policy bind process has been completed.

{
    'event': 'policy_bind_failed,
    'webhook': 'https://www.example.com/my-webhook',
    'data': {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "master_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "policy_number": "string",
        "customer": {
            "first_name": "string",
            "last_name": "string",
            "email_address": "string"
        },
        "policy_status": "BIND_FAILED",
        "issued_date": "2022-09-05",
        "expiration_date": "2022-09-05",
        "effective_date": "2022-09-05",
        "quote_date": "2022-09-05",
        "policy_attributes": {},
        "premium_amount": 0,
        "quote_id": "string",
        "is_test": true
    }
}

policy_purchase_invalid

This event is similar to the policy_bind_failed event but is sent when a batch purchase is made and 1 or more policies in the batch failed to bind.

{
    'event': 'policy_purchase_invalid',
    'webhook': 'https://www.example.com/my-webhook',
    'data': {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "master_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "policy_number": "string",
        "customer": {
            "first_name": "string",
            "last_name": "string",
            "email_address": "string"
        },
        "policy_status": "PENDING",
        "issued_date": "2022-09-05",
        "expiration_date": "2022-09-05",
        "effective_date": "2022-09-05",
        "quote_date": "2022-09-05",
        "policy_attributes": {},
        "premium_amount": 0,
        "quote_id": "string",
        "is_test": true
    }
}

policy_payment_failed

Sent when a payment for a policy purchase fails.

{
    'event': 'policy_payment_failed',
    'webhook': 'https://www.example.com/my-webhook',
    'data': {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "master_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "policy_number": "string",
        "customer": {
            "first_name": "string",
            "last_name": "string",
            "email_address": "string"
        },
        "policy_status": "REQUIRES_PAYMENT",
        "issued_date": "2022-09-05",
        "expiration_date": "2022-09-05",
        "effective_date": "2022-09-05",
        "quote_date": "2022-09-05",
        "policy_attributes": {},
        "premium_amount": 0,
        "quote_id": "string",
        "is_test": true
    }
}

policy_canceled

Sent when a policy is canceled.

{
    'event': 'policy_canceled,
    'webhook': 'https://www.example.com/my-webhook',
    'data': {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "master_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "policy_number": "string",
        "customer": {
            "first_name": "string",
            "last_name": "string",
            "email_address": "string"
        },
        "policy_status": "CANCELED",
        "issued_date": "2022-09-05",
        "expiration_date": "2022-09-05",
        "effective_date": "2022-09-05",
        "quote_date": "2022-09-05",
        "policy_attributes": {},
        "premium_amount": 0,
        "quote_id": "string",
        "is_test": true
    }
}