Automating insurance compliance

Learn how to use our webhooks to track coverage status in real-time.

Using webhook events to track compliance

1099Policy sends notifications to your app using webhooks. Webhooks are important for tracking compliance since contractors can complete and cancel their coverage at any time. Without webhooks, you would have no visibility into coverage activations, cancellations or any other asynchronous activity.

To use webhooks to track compliance:

Create a webhook endpoint in your app.
Add logic to handle 1099Policy events. For contractor insurance, these include changes to the state of coverage, like moving from active to cancelled or application started to active policy.
Test your webhook endpoint to confirm that it’s working as expected.

Webhook events

When a contractor completes their application, we send a policy.active event to your webhook URL that takes the following format:

{
  data: {
    id: "pl_iJ5A9JKnG8",
    is_active: true,
    quote: "qt_aFjVlfRrAe",
    pdf_url: "https://storage.googleapis.com/bound-policies/sandbox/ten99policy_gl_coi_pl_WzFRszJhoY_1696015724.pdf",
    certificates: {
        wc_coi_pdf_url: "https://storage.googleapis.com/bound-policies/sandbox/ten99policy_wc_coi_pl_WzFRszJhoY_1696015722.pdf",
        gl_coi_pdf_url: "https://storage.googleapis.com/bound-policies/sandbox/ten99policy_gl_coi_pl_WzFRszJhoY_1696015724.pdf"
    },
    expiration_date: "2023-11-01T00:00:00",
    effective_date: "2023-09-27T05:37:06.742302",
    created: "2023-09-29T19:26:32.500931"
  },
  type: "policy.active",
  created: 1696015731
}

Every job assignment that the creator takes after they complete their insurance application is reported to back to 1099Policy via the assignment api. Once the creator’s credit card is successfully charged we’ll post the following assignment.active webhook event:

{
    data: {
        id: "an_rDpc5e7D2s",
        certificates: {
            wc_coi_pdf_url: "https://storage.googleapis.com/bound-policies/sandbox/ten99policy_wc_coi_pl_nX7q7exY4Z_an_rDpc5e7D2s_1695515634.pdf",
            gl_coi_pdf_url: "https://storage.googleapis.com/bound-policies/sandbox/ten99policy_gl_coi_pl_nX7q7exY4Z_an_rDpc5e7D2s_1695515635.pdf"
        },
        job: "jb_YuBZ3r7W2k",
        contractor: "cn_HoQsfQ2nLa",
        end_date: "2024-04-20T17:00:00",
        effective_date: "2023-09-20T19:49:46.171000",
        created: "2023-09-20T19:52:48.880241"
    },
    type: "assignment.active",
    created: 1695515637
}

Here's a list of events that 1099Policy publishes that you'll want to listen for:

EVENT	DATA OBJECT TYPE	DESCRIPTION
`policy.active`	`policy`	Takes place when a contractor successfully completes their insurance application and is confirmed as having paid the premium for their insurance coverage.
`policy.cancelled`	`policy`	Takes place when a contractor explicitly cancels their insurance coverage.
`application.started`	`session`	Takes place when a contractor starts their insurance application.
`application.expired`	`session`	Takes place when the insurance application expires.
`assignment.active`	`assignment`	Takes place when 1099Policy receives notification of a new contractor assignment and that assignment is confirmed as having been paid.

Webhook Signature Verification

Webhook signatures are strings used to verify the validity of a webhook event sent from 1099Policy to your registered webhook endpoint. You'll want to validate to prevent malicious webhook requests. This signature is passed as header values in the format: x-convoy-signature.

Here's an example in python of how you verify the webhook signature.

import hmac
import hashlib

secret = b'[webhook_secret_key]'
# ^ available under the webhook tab on the dashboard

request_data = b'[convoy-timestamp],[request_payload]'
# ^ convoy-timestamp included as part of the POST request header

digest = hmac.new(secret, request_data, hashlib.sha512).hexdigest()
signature = '[x-convoy-signature]'
# ^ x-convoy-signature included as part of the POST request header

hmac.compare_digest(signature, digest)