Event Notifications through Subscriptions

Communication from the ShowingHub to the Listing and Buying Applications are done through webhooks. The webhooks are sent via the Showinghub to the application when needed. When the application is created, you supply the URL of your web service that handles the ShowingHub requests. Each request can be for different things – maybe the MLS is approving a registration or possibly a Buyer Application sends a request to schedule an appointment. Regardless, each request comes from the ShowingHub with an eventName indicating the purpose. Although the list is below, examples and definitions of the webhooks are throughout this guide. Some of these may be only for the Listing Application, Buyer Application, MLS, or all.

  • AppointmentCancelled
  • AppointmentConfirmed
  • MessageCreated
  • MlsCreated
  • MlsUpdatedNotifyWebhookFailure
  • Ping
  • RegistrationCreated
  • RegistrationRequestApproved
  • RegistrationRequestCreated
  • RegistrationRequestDisapproved
  • RegistrationTransferred
  • RegistrationUpdated
  • RequestAccepted
  • RequestCancelled
  • RequestCreated
  • RequestDeclined
  • VerificationMessage

Subscription Security

For enhanced security, you can include key-value pairs in the HTTP request headers when making calls to your webhook. It is a best practice to create headers and validate them within your API to ensure the request is genuinely originating from ShowingHub. If you're working with multiple applications across different MLSs, you can assign distinct header values for each hub, allowing you to identify which MLS the request pertains to.

Additionally, you have the flexibility to utilize as many request headers as needed. These headers can serve various purposes, such as bypassing firewalls or enhancing security and tracking.

Please note that only one subscription is allowed per application at this time.

All specified header values can be accessed via the PUT /subscriptions/{subscriptionId} endpoint, as detailed below.

Safety Features

Besides the security http request headers above, there are a number of safety features when the ShowingHub sends a request to your API. If the Showinghub sends a request to your API and a non-http 2xx is returned, then it will repeat the request 2 more times several seconds later. If there is still a problem, the ShowingHub will inactivate the subscription and email the contact email that on the application. Once your API is fixed, then you can re-activate the subscription.

Subscription Maintenance

Subscriptions API’s are provided to self-manage your webhooks. The subscription contains the url and request headers to reach your API.

This list is meant to provide overview and design insight.

  • 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 delivered when you hit /activate. We cannot guarantee 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 parameters:

      • 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.