Real-time Updates via Webhooks

An overview of Root's real-time update capabilities and catalog of webhook payloads

Once you've been on-boarded onto the Carrier Platform API, Root can configure your application to receive automated messages when important events happen. They have a message—or payload—which is sent to a single URL on your server. You can also configure a unique URL per message if it better suits your application. Webhooks almost always provide faster updates than polling.

To receive our webhooks, you will need to set up a web application that can receive POST requests containing the payloads detailed below; we expect a response with status 200 to signal the webhook was received successfully. Recipients should be prepared to deduplicate webhook events based on the unique id in the payload, as well as be capable of re-ordering events according to the timestamp within the payload should events be received out of order.

Envelope (Top-level Keys)

Root's events will generally comply with the CloudEvents specification. In addition, consumers from Root should expect consistent structure within source and type and consistent presence of keys CloudEvents specifies as optional, detailed below.

Key	Type	Description
specversion	String	Version of CloudEvents
id	String	Unique identifier to deduplicate resent events
time	Timestamp	ISO8601 time when the event occurred (not necessarily when the event was sent, be ready to receive backdated and out-of-order events)
source	URI	Will always contain root.com with a path concerning the domain the event relates to (such as /policy)
type	String	A reverse-DNS event name taking the form com.root.subject.past-tense-verb.version
datacontenttype	String	The MIME type of data, typically "application/json"
data	JSON	The nested JSON data specific to the particular event

Events Catalog

Quoting-related Events

TCPA Consent Collected

Occurs at most once per quoteId as soon as TCPA consent is given.

json

{
  "specversion": "1.0",
  "id": "uuid",
  "time": "ISO8601 Timestamp",
  "source": "root.com/quoting",
  "type": "com.root.tcpa-consent.collected.v2",
  "datacontenttype": "application/json",
  "data": {
    "quoteId": "uuid",
    "tcpaConsentTimestamp": "ISO8601 Timestamp"
  }
}

Quote Estimated

Occurs each time a new RC1 generates in the course of quoting. Note that depending on the channel and the user's behavior this may happen a significant number of times. The user may not see every RC1 generated as the quoting happens asynchronously and they may have already moved on to make further changes.

json

{
  "specversion": "1.0",
  "id": "uuid",
  "time": "ISO8601 Timestamp",
  "source": "root.com/quoting",
  "type": "com.root.quote.estimated.v2",
  "datacontenttype": "application/json",
  "data": {
    "quoteId": "uuid"
  }
}

Quote Finalized

Occurs at least once prior to binding (i.e. purchasing) a policy. But can occur any number of times, including zero times should a prospect not continue through the quoting process to finalization.

json

{
  "specversion": "1.0",
  "id": "uuid",
  "time": "ISO8601 Timestamp",
  "source": "root.com/quoting",
  "type": "com.root.quote.finalized.v2",
  "datacontenttype": "application/json",
  "data": {
    "quoteId": "uuid"
  }
}

Quote Rated

Occurs each time a new RC3 generates in the course of quoting. Note that depending on the channel and the user's behavior this may happen many times. The user may not see every RC3 generated as the rating happens asynchronously and they may have already moved on to make further changes.

json

{
  "specversion": "1.0",
  "id": "uuid",
  "time": "ISO8601 Timestamp",
  "source": "root.com/quoting",
  "type": "com.root.quote.rated.v2",
  "datacontenttype": "application/json",
  "data": {
    "quoteId": "uuid"
  }
}

Policy-related Events

Policy Bound

Occurs once per policy bind (i.e. initial purchase of a policy)

json

{
  "specversion": "1.0",
  "id": "uuid",
  "time": "ISO8601 Timestamp",
  "source": "root.com/policy",
  "type": "com.root.policy.bound.v2",
  "datacontenttype": "application/json",
  "data": {
    "quoteId": "uuid",
    "policyId": "uuid",
    "policyNumber": "string",
    "effectiveTimestamp": "ISO8601 Timestamp"
  }
}

Policy Canceled

Occurs when a policy is canceled and coverage concludes.

json

{
  "specversion": "1.0",
  "id": "uuid",
  "time": "ISO8601 Timestamp",
  "source": "root.com/policy",
  "type": "com.root.policy.canceled.v2",
  "datacontenttype": "application/json",
  "data": {
    "policyId": "uuid",
    "policyNumber": "string",
    "effectiveTimestamp": "ISO8601 Timestamp"
  }
}

Policy Endorsed

Occurs each time a policy is changed, such as different limits or deductible or a new vehicle added. Note that changes may be future dated (effectiveTimestamp later than time).

json

{
  "specversion": "1.0",
  "id": "uuid",
  "time": "ISO8601 Timestamp",
  "source": "root.com/policy",
  "type": "com.root.policy.endorsed.v2",
  "datacontenttype": "application/json",
  "data": {
    "policyId": "uuid",
    "policyNumber": "string",
    "effectiveTimestamp": "ISO8601 Timestamp"
  }
}

Policy Reinstated

Occurs when a policy is reinstated after a period of lapse. Note that effectiveTimestamp may be future dated.

json

{
  "specversion": "1.0",
  "id": "uuid",
  "time": "ISO8601 Timestamp",
  "source": "root.com/policy",
  "type": "com.root.policy.reinstated.v2",
  "datacontenttype": "application/json",
  "data": {
    "policyId": "uuid",
    "policyNumber": "string",
    "effectiveTimestamp": "ISO8601 Timestamp"
  }
}

Policy Renewed

Occurs when a new policy term begins after the conclusion of the prior policy term. The policyNumber will remain consistent between the two terms.

json

{
  "specversion": "1.0",
  "id": "uuid",
  "time": "ISO8601 Timestamp",
  "source": "root.com/policy",
  "type": "com.root.policy.renewed.v2",
  "datacontenttype": "application/json",
  "data": {
    "policyId": "uuid",
    "policyNumber": "string",
    "effectiveTimestamp": "ISO8601 Timestamp"
  }
}