Status Updates

Webhooks

Opendoor has the ability to send notifications using webhooks, to keep your application in-sync with status updates for referrals. In order to enable webhooks, you must first provide Opendoor with a webhook URL. You can configure this URL within the developer dashboard.

Optionally, you can provide a unique trackingId when querying for a partner referral link (See our Creating Referrals walkthrough for an example of this). If provided, Opendoor will return the trackingId in the webhook payload.

Webhook notifications will always be HTTP POST requests to your provided webhook URL and the payload will be shaped as follows:

{
  sellerInputId: <SELLER_INPUT_ID>,
  trackingId: <TRACKING_ID>,
  eventType: <EVENT_TYPE>,
  eventMetadata: <EVENT_METADATA>
}

Fields

Field name	Description
`trackingId`	A string that represents the unique tracking identifier you provided when you requested a referral link. If an identifier wasn’t provided, this field will be blank.
`eventType`	A string that represents the type of notification event.
`eventMetadata`	A JSON object that is tightly coupled with `eventType`. See below for some example event types and the expected metadata for each.

Webhook Event Types

Type	Description
State Transition	The state transition event will trigger whenever the state for an Opendoor lead or offer has changed. States are included in the `eventMetadata` field in the payload in a subfield named `state`.
Customer Update	The customer update event will trigger when certain actions that do not change the state of an Opendoor lead or offer occur. Updates are included in the `eventMetadata` field in the payload in a subfield named `update`.

See the bottom of this page for all the possible state and update values. There are several values a lead can be in. Some special values are discussed now.

Offer.sent Details

If the state is offer.sent, an additional field - offerUrl - will be applied to eventMetadata. offerUrl is a string and represents a URL to the customer’s Opendoor offer presentation. The offer presentation is a portal where the customer can view the details on their offer and accept it.

Lead.denied Details

If the state is lead.denied, an additional field - denialReason - will be applied to eventMetadata. denialReason is a string. You can find a full list of our denial reasons along with their explanations at the bottom of this page.

Offer_expiring_soon Details

If the update is offer_expiring_soon, an additional field - offerExpiresAt - will be applied to eventMetadata. offerExpiresAt is a string and represents the time the offer will expire. The time is a UTC timestamp formatted according to ISO 8601. It will be of the form "2009-11-10T23:00:00Z".

Referral_handover_occurred Details

If the update is referral_handover_occurred, an additional field - handoverOccurredAt - will be applied to eventMetadata. handoverOccurredAt is a string and represents the time the seller first requested to view the hub via the partner. The time is a UTC timestamp formatted according to ISO 8601. It will be of the form "2009-11-10T23:00:00Z".

Coe_date_change Details

If the update is coe_date_change, an additional field - coeDate - will be applied to eventMetadata. coeDate is a string and represents the close of escrow time. The time is a UTC timestamp formatted according to ISO 8601. It will be of the form "2009-11-10T23:00:00Z".

Offer.in_contract Details

If the state is offer.in_contract, additional fields - finalizedRecordedPriceCents, finalizedRepairPriceCents, finalizedFeePriceCents, coeDate - will be applied to eventMetadata. finalizedRecordedPriceCents is an integer and represents the final offer amount in cents. finalizedRepairPriceCents is an integer and represents the final repair amount in cents. finalizedFeePriceCents is an integer and represents the final fee amount in cents. coeDate is a string and represents the close of escrow time. The time is a UTC timestamp formatted according to ISO 8601. It will be of the form "2009-11-10T23:00:00Z".

finalized_offer_sent Details

If the update is finalized_offer_sent, an additional field - finalizedRecordedPriceCents - will be applied to eventMetadata. finalizedRecordedPriceCents is an integer and represents the final offer amount in cents. Additional fields -finalizedRepairPriceCents and finalizedFeePriceCents - may also be applied to eventMetadata if available. finalizedRepairPriceCents is an integer and represents the final repair amount in cents. finalizedFeePriceCents is an integer and represents the final fee amount in cents.

Offer.refreshed Details

If the update is offer_refreshed, an additional field - offerUrl - will be applied to eventMetadata. offerUrl is a string and represents a URL to the customer’s Opendoor offer presentation. The offer presentation is a portal where the customer can view the details on their offer and accept it.

Video_walkthrough_scheduled Details

If the update is video_walkthrough_scheduled, additional fields - videoWalkthroughTime, videoWalkthroughId- will be applied to eventMetadata. videoWalkthroughTime is a string and represents the time the walkthrough is scheduled. The time is a UTC timestamp formatted according to ISO 8601. It will be of the form "2009-11-10T23:00:00Z". videoWalkthroughId is a string and represents the unique identifier for a video_walkthrough_scheduled event.

Video_walkthrough_canceled Details

If the update is video_walkthrough_canceled, an additional field - videoWalkthroughId- will be applied to eventMetadata. videoWalkthroughId is a string and represents the unique identifier for the video_walkthrough_scheduled event that was cancelled.

Webhook Examples

Examples of what a webhook notification payload looks like for a lead.denied, offer.sent , offer_expiring_soon and video_walkthrough_scheduled events.

{
  trackingId: 'E5588245-27BF-42B2-AF27-E39868CCA40D',
  eventType: 'stateTransition',
  eventMetadata: {
    state: 'lead.denied',
    denialReason: 'ADDRESS'
  }
}

{
  trackingId: 'E5588245-27BF-42B2-AF27-E39868CCA40D',
  eventType: 'stateTransition',
  eventMetadata: {
    state: 'offer.sent',
    offerUrl: 'https://consumer.opendoor.com/seller-offer/123',
    offerUrlPrintable: '<Deprecated field. Do not use.>'
  }
}

{
  eventMetadata: {
    update: 'offer_expiring_soon',
    offerExpiresAt: '2009-11-10T23:00:00Z',
  },
  eventType: 'customerUpdate',
  trackingId: 'E5588245-27BF-42B2-AF27-E39868CCA40D',
  sellerInputId: "75BA29DD-03BE-4289-BDAC-7A9E024DF803"
}

{
  eventMetadata: {
    update: "video_walkthrough_scheduled",
    videoWalkthroughTime: "2009-11-10T23:00:00Z",
    videoWalkthroughId: "4a48c18893dd74ab9f435de4bc34b250a5ffd01d5b1af78269aecc59ec2f597b"
  },
  eventType: "customerUpdate",
  sellerInputId: "75BA29DD-03BE-4289-BDAC-7A9E024DF803",
  trackingId: "E5588245-27BF-42B2-AF27-E39868CCA40D"
}

{
  eventMetadata: {
    update: "referral_handover_occurred",
    "handoverOccurredAt": "2009-11-10T23:00:00Z"
  },
  eventType: "customerUpdate",
  sellerInputId: "75BA29DD-03BE-4289-BDAC-7A9E024DF803",
  trackingId: ""
}

Possible `state` values

Some of these states are only available through Webhooks or the Lead Status API exclusively. Wherever that is the case, it will be mentioned below in the Notes. All other states will be available through both the Webhooks and the Lead Status API.

State	Description	Notes
`lead.seller_flow_incomplete`	The lead has not yet completed Opendoor’s seller flow questionnaire	This status is only available via the Lead Status API and not through the Webhooks
`lead.denied`	The lead has been denied eligibility to sell to Opendoor
`lead.qualified`	The lead has been qualified to sell direct to Opendoor
`offer.sent`	The offer has been sent to the seller
`offer.viewed`	The seller has viewed their initial offer	This status is only available via the Webhooks and not through the Lead Status API
`offer.expired`	The seller’s Opendoor offer has expired
`offer.accepted`	The finalized offer has been seen by the seller
`offer.in_contract`	The seller is now In Contract with Opendoor
`offer.withdrawn`	The seller has withdrawn from the offer process
`offer.contingencies_released`	Contingencies have been released on the seller’s sale to Opendoor!
`offer.closed`	The seller has reached the close of escrow process on an offer

Possible `denial` values

This is the complete list of denial codes that are used in the Webhooks and Lead Status API.

Denial reasons are subject to change and may or may not apply to particular homes, products, or markets.

Denial Reason	Description
`ACTIVE_OFFER`	It looks like there’s already an active offer on this address! If you originally requested this offer, please check your email for your offer details.
`ADDRESS`	We’re not in your area yet, but we are expanding quickly.
`AGE_RESTRICTED_COMMUNITY`	We currently aren’t buying homes in age-restricted communities.
`ASBESTOS_SIDING`	We currently don’t buy homes with asbestos siding.
`YEAR_BUILT_BELOW_MIN`	We currently aren’t buying homes this old in this area.
`DWELLING_TYPE`	We’re currently only buying single-family homes and condominiums in this area.
`FIRE_DAMAGE`	We currently aren’t buying homes that have previous or current fire damage.
`FLOOD_HISTORY`	We currently aren’t buying homes that have a history of flooding.
`FLOOD_ZONE`	We currently aren’t buying homes in or near flood zones.
`FOUNDATION`	We currently aren’t buying homes with known foundation issues.
`GATED_COMMUNITY`	We currently aren’t buying homes in gated communities in this area.
`IN_CONTRACT_WITH_OPENDOOR`	An offer has already been requested for this home.
`LACK_OF_ADEQUATE_COMPS`	Your home has unique characteristics that set it apart from the rest. Unfortunately, those features also make it difficult for us to compare your home to others and make you an offer. We’re constantly working on improving our valuations, and we hope to be able to make you an offer in the future.
`LEASED_SOLAR_PANELS`	We currently aren’t buying homes with non-prepaid leased solar panels.
`LISTED_BY_OPENDOOR`	This home has already been sold to Opendoor.
`LOT_SQ_FT`	We currently aren’t buying homes on lots this large in this area.
`NON_BUYBOX_DWELLING_TYPE`	We’re currently only buying single-family homes and condominiums in this area.
`OTHER_DENIAL_DETAIL`	We make competitive offers by analyzing comparable home sales and market data in the area. In some cases like yours, we have insufficient information, such as lack of strong comps sold recently, or other high risk factors that make it difficult for us to value your home at this time.
`OTHER_DENIAL_GENERAL`	We can’t currently make an offer on this home.
`OWNED_BY_OPENDOOR`	This home has already been sold to Opendoor.
`POLYBUTYLENE_PIPING`	We currently aren’t buying homes with polybutylene piping.
`PREPARING_OFFER`	It looks like there’s already an active offer on this address! If you originally requested this offer, please check your email for your offer details.
`PRIVATE_POOL`	We currently are not buying homes in this area with private pools.
`SEPTIC`	We currently aren’t buying homes in this area with septic sytems.
`SHARED_LOT`	We currently aren’t buying homes in this area that have a shared lot with neighbors.
`TENANT_OCCUPIED`	We currently aren’t buying homes in this area that are tenant-occupied.
`UNPERMITTED_ADDITION`	We currently are not buying homes in this area with unpermitted additions.
`VALUATION_TOO_HIGH`	We believe your home’s value falls above the range we purchase homes in.
`VALUATION_TOO_LOW`	We believe your home’s value falls below the range we purchase homes in.
`WELL_WATER`	We currently are not buying homes with private wells as the primary water source.
`YEAR_BUILT`	We currently aren’t buying homes this old in this area.

Possible `update` values

These update values are available through webhooks as part of customer update events. Update values are subject to change and may or may not apply to particular homes, products, or markets.

Update	Description
`coe_date_change`	The seller has changed their close of escrow date.
`finalized_offer_sent`	Underwriting is completed and the seller has been contacted that their final offer is ready.
`offer_expiring_soon`	The Opendoor offer is about to expire soon.
`offer_refreshed`	The seller has requested an updated offer, after an existing offer has expired.
`referral_handover_occurred`	Opendoor has received the seller’s first request to view the offer on the Opendoor dashboard from a partner via the offer URL. This event will be fired only the first time the seller requests to view the offer.
`video_walkthrough_canceled`	The seller has canceled a scheduled offer review virtual assessment
`video_walkthrough_completed`	The seller has completed the self-service virtual assessment video upload or the offer review virtual assessment.
`video_walkthrough_scheduled`	The seller has scheduled an offer review virtual assessment.