The mechanism used by the showing hub for outbound communications and event notifications for showing vendors and the MLS.

Last update June 15 DR

Message Types

A field of the webhook payload called webhookMessageType will specify what event caused us to hit you.

• The buyer's app should immediately hit /appointments/{appointmentId}/acknowledge to confirm receipt of the appointment accepted appointment.

Format and Payload

A webhook will contain a JSON post body that will include a single webhookMessageType from the above table.

The entity in question, if any, will appear in the message body. A call to notify the app about accepted appointment request, for instance, will include the new Appointment object in its payload.

TODO: Payload examples for webhooks of each type.

Security

For security purposes, you can supply strings to be used as the name and value of an HTTP request header on our calls to your webhook. You should implement a check on this to validate that a hit on your webhook is really coming from a Hub. You can also give differen hubs different values to discriminate which MLS's hub is the source of the hit.

In addition, the hub allows you to specify an arbitrary list of names and values to use as additional HTTP request headers. Some users may need these to penetrate filewalls or for other security/tracking purposes.

All these header values are accessible at the PUT /subscriptions/{subscriptionId} endpoint described below.

Management and Error Recovery

A collection of API endpoints are provided for you to self-manage your webhooks. We think of webhooks as "subscriptions", within which a URL, a security config, and a list of topics combine into a set of complete instructions for conveying events and state changes to a consumer.

In the Preview release, an Application entity will have exactly one Subscription. In future versions, we plan to expand this so you can configure different endpoints for different topics, or redendant endpoints, etc. The list of topics for a Subscription will always be empty in Preview.

This list is meant to provide overview and design insight. See the Swagger document for full API documentation.

• GET /app/v1/subscriptions [/{subscriptionId}] PUT /app/v1/subscriptions/{subscriptionId} This is where you can see and update the key values of your webhook. The GET endpoint without the optional Webhook details are returned in an array (of exactly one element, in Preview).

• POST /app/v1/subscriptions/{subscriptionId}/deactivate
POST /app/v1/subscriptions/{subscriptionId}/activate Use these two endpoints to manually control the enablement of this webhook. If you need to take your webhook down for maintenance, for instance, you can hit /deactivate. Messages will queue and then be delievered when you hit /activate. We cannot guaratee the queued messages will come in order, so you will want to queue them up on your end and go through them by timestamp.

• GET /app/v1/subscriptions/{subscriptionId}/status - Returns status and analytical facts about this webhook

  This endpoint accepts an optional query string parameter "startTime" (DateTimeOffset).

  • status - Possible values: Enabled, DisabledDueToError, DisabledManually
  • retries - The number of retries the hub is configured to make before disabling your endpoint
  • errors - The number of errors from startTime to now (or 24 hour if no startTime provided)
  • attempts - The number of attempts from startTime to now (or 24 hour if no startTime provided)
  • messagesPending - The number of queued messages awaiting a send attempt

• GET /app/v1/subscriptions/{subscriptionId}/history - Shows the history of message attempts against your webhook. Subject to data retention rules configured per hub.

  Query-string paramters:

  • failed (bool) - Apply a filter to show only attempts that received a non-2xx response
  • includeMessages (bool) - Fold the WebhookMessage entities into the payload (could be large)
  • startDateTime (dateTimeOffset)
  • endDateTime (dateTimeOffset)

  Response payload includes an array of attempt objects:

  • id
  • eventOccurredOn (dateTimeOffset) - the triggering event's createdOn value
  • attemptedOn (dateTimeOffset) - When the attempt was made
  • responseStatusCode - HTTP code we got back from your webhook
  • response - Response body from your webhook
  • webhookMessageId - the ID of the message that was sent in this attempt
  • webhookMessage - if "includedMessages" param is Y, an embedded object that is the webhook content we attempted to post to you
  • webhookMessageType - The type of message this was
  • attemptNumber - The number of attempts this is to get this webhookMessage through

• GET /app/v1/subscriptions/messages/{messageId} - Endpoint to get a single WebhookMessage by ID Note this is NOT pathed through /subscription. All messages for all your subscriptions (of which in this version you have exactly one) are available on this endpoint.