Consumer Documentation for EntityEvent Push Replication

Our Producer API leverages the RESO EntityEvent Resource model to push data efficiently and directly to your Consumer API using webhooks. This eliminates the need for continuous polling by your system and simplifies event-driven data replication.

API Endpoint Requirements

To integrate with our Producer API, you must set up an API endpoint to receive EntityEvents:.

  • HTTP Method: POST
  • Content-Type: application/json
  • Authorization: OAuth2 Bearer Token

Authentication

Your endpoint must support OAuth2 Bearer Token authentication. You may provide us with either:

  • A fixed token
  • Or credentials for dynamic token generation:
    • ClientId
    • ClientSecret
    • AccessTokenURL
    • GrantType

Additionally, you must provide a PostEndpoint URL for delivering events.

Example Request Header

Authorization: Bearer <your_oauth_token>

Payload Structure

Each event payload will be sent using the RESO EntityEvent structure along with a custom Data object containing the actual data resource, e.g., Property, Member, Office, or an internal resource such as Media.

Example Payload

{
  "@reso.context": "urn:reso:metadata:2.0:resource:entityevent",
  "value": [
    {
      "EntityEventSequence": 1101,
      "ResourceName": "Property",
      "ResourceRecordKey": "235021",
      "Data": {
        // Complete RESO Property object
      }
    },
    {
      "EntityEventSequence": 1111,
      "ResourceName": "Media",
      "ResourceRecordKey": "ABC123",
      "Data": {
        "ResourceRecordID": "ABC123",
        "OriginatingSystemName": "YourSystemName",
        "Media": [
          // Media array
        ]
      }
    }
  ]
}

Consumer API Expectations

  • Accept HTTP POST requests
  • Respond promptly (typically within a few seconds)
  • Handle batches of events gracefully
  • Implement polite behaviors for backpressure scenarios:
    • Respond with HTTP 429 if overwhelmed
    • Include a Retry-After header to indicate retry delay

Example Successful Response

HTTP/2 200
Content-Type: application/json

Example Retry Response

HTTP/2 429
Content-Type: application/json
Retry-After: 60

RESO Requirements for Consumer API

To ensure compatibility with the RESO standardized Push Replication using Webhooks, your Consumer API must meet the following requirements:

  • Consumers MUST implement an API endpoint that can receive EntityEvents
  • Consumers MUST establish authorization with the provider, using an OAuth2 bearer token

Optional Header: EntityEventSource

If you need to distinguish between multiple sources, support the optional header:

EntityEventSource: IDX Feed 123

Handling Media Resources

Media resources will be included as objects within the Data property. Your system should be prepared to retrieve and store these media files.

Citations