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": 1698796800,
"effective_date": 1695793026,
"created": 1696015592
},
"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": 1713632400,
"effective_date": 1695239386,
"created": 1695239568
},
"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 | Occurs when a contractor successfully completes their insurance application and is confirmed as having paid the premium for their insurance coverage. |
policy.cancelled | policy | Occurs when a contractor explicitly cancels their insurance coverage. |
application.started | session | Occurs when a contractor starts their insurance application. |
application.expired | session | Occurs when the insurance application expires. |
application.manual_review | session | Occurs when the insurance application is moved into manual review. |
application.manual_review_approved | session | Occurs when the insurance application under manual review is approved. |
application.ineligible | session | Occurs when the contractor completing the insurance application is ineligible for insurance coverage based on information provided in the insurance application. |
assignment.active | assignment | Occurs when 1099Policy receives notification of a new contractor assignment and that assignment is confirmed as having been paid. |
assignment.cancelled | assignment | Occurs when 1099Policy receives notification that an assignment is cancelled. |
certificate.approved | certificate | Occurs when a certificate of insurance passes all automated review requirements. |
certificate.flagged | certificate | Occurs when a certificate of insurance fails some automated review requirements and may require manual review. |
certificate.denied | certificate | Occurs when a certificate of insurance is denied during automated review. |
invoice.charge_card_failed | invoice | Occurs when a charge attempt fails. |
invoice.charge_card_succeeded | invoice | Occurs when a charge attempt succeeds. |
category_code.added | category_code | Occurs when a new category code is added. |
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)