Register webhooks to receive real-time notifications of key events, such as all policy data becoming available after an end-user submits on your Canopy Connect widget.

To register a webhook, specify a web endpoint and select the event types you wish to subscribe to. Canopy Connect's infrastructure will send POST requests to the web endpoint you specify. You can register webhooks from the Settings page on the Canopy Connect dashboard or using the Webhooks API.

Each webhook request represents an event occurring on a specific data Pull. You can use the returned pull_id to fetch the complete information for the data Pull using the GET /pulls/:pullId endpoint.

Webhook Request Format

The webhook is a POST request with a JSON body of the form:

{
  "widget_id": "<WIDGET_ID>", // widget_id of the Widget the Pull was submitted on
  "pull_id": "<PULL_ID>", // pull_id of the Pull this event is associated with
  "status": "SUCCESS", // status of the Pull at the time the event occurred
  "meta_data": {... developer-supplied JSON-serializable metadata ...},
  "event_type": "COMPLETE", // webhook event type
  "data": { 
    "policy_id": "<POLICY_ID>", // Returned with the POLICY_AVAILABLE event. policy_id of the Policy that is available
    "policy_type": "<POLICY_TYPE>" // Returned with the POLICY_AVAILABLE event. Policy type
    "initial_pull_id": "<PULL_ID>" // For synced accounts, the Pull ID of the first Pull of the account
  }
}

Event Types

There are 3 event types you can subscribe to:

Event TypeDescription
AUTH_STATUSThis event type is only relevant to you if you are fully white-labeling the end-user authentication experience.

This event is triggered when a Pull transitions to a new authentication state. The webhook request body includes a sequence value. The sequence value is an incrementing number that you can use to avoid issues when webhook requests arrive out of order over the network. The sequence number will always go up by at least one for each authentication state change that occurs on a Pull. When designing your user interface, you only need to go "backwards" when hitting a status that requires user input. Those statuses are NOT_AUTHENTICATED, IDENTITY_VERIFICATION_OPTIONS and IDENTITY_VERIFICATION.

Read the auth_status value from the webhook request body.

- If NOT_AUTHENTICATED: Prompt end-user to submit carrier login
- If IDENTITY_VERIFICATION_OPTIONS: Prompt end-user to select an identity verification method from one of the available options returned in the webhook request body
- If IDENTITY_VERIFICATION_OPTIONS: Prompt end-user to submit their 2-factor authentication code
POLICY_AVAILABLEThis event is triggered when the policy data for an insurance policy becomes available. If the end-user has no insurance policies, this event will not trigger. If the end-user has 5 insurance policies, you will receive 5 POLICY_AVAILABLE webhook requests.
POLICIES_AVAILABLEThis event triggers once per Pull, when policy data for all insurance policies is available. Does not include documents.
COMPLETEThis event occurs once per Pull, once all information (including documents) is available.