Domain Group Webhooks

asyncapi: 3.0.0
info:
  title: Domain Group Webhooks
  version: v1
  description: |
    Event surface for the Domain Public API. Domain does not publish an AsyncAPI
    document; this one is generated by API Evangelist strictly from Domain's
    published webhook documentation at
    https://developer.domain.com.au/docs/latest/apis/pkg_webhooks and its
    Configuration / Creating Subscriptions / Processing Notifications guides.
    Every channel, message field, header and status code below appears verbatim
    in those pages - nothing has been invented.

    Delivery model: Domain POSTs a JSON **array** of notifications to the
    developer-registered endpoint (batched to reduce load), signed with an
    HMAC-SHA1 `X-Domain-Signature` header keyed on the webhook's Verification
    Code. The consumer must acknowledge with `204 No Content` before doing any
    processing.
  contact:
    name: Domain API Support
    email: api@domain.com.au
    url: https://developer.domain.com.au/docs/latest/support
  termsOfService: https://www.domain.com.au/group/api-terms-and-conditions/
  externalDocs:
    description: Domain Webhooks documentation
    url: https://developer.domain.com.au/docs/latest/apis/pkg_webhooks

defaultContentType: application/json

servers:
  consumer:
    host: example.com
    protocol: https
    pathname: /domain-webhook/
    description: >-
      The consumer-hosted HTTPS endpoint registered as a Webhook on a Domain
      developer-portal project. Must be publicly resolvable with a valid
      (non self-signed) TLS certificate, and must answer the verification
      challenge before any notification is delivered.

channels:
  agencies:
    address: agencies
    title: Agency changes
    description: Notified when agency details are changed. Resource id is agencyId, readable via GET /v1/agencies/{id}/.
    messages:
      notificationBatch:
        $ref: '#/components/messages/NotificationBatch'
  agents:
    address: agents
    title: Agent changes
    description: Notified when agent details are changed. Resource id is agentId, readable via GET /v1/agents/{id}/.
    messages:
      notificationBatch:
        $ref: '#/components/messages/NotificationBatch'
  enquiries:
    address: enquiries
    title: Enquiries
    description: Enquiries submitted to agents from listings. Resource id is enquiryId, readable via GET /v1/enquiries/{id}/.
    messages:
      notificationBatch:
        $ref: '#/components/messages/NotificationBatch'
  listings:
    address: listings
    title: Listing changes
    description: Updates as listings are created, updated or deleted. Resource id is listingId, readable via GET /v1/listings/{id}/.
    messages:
      notificationBatch:
        $ref: '#/components/messages/NotificationBatch'
  projects:
    address: projects
    title: Project changes
    description: Updates as projects are created, updated or deleted. Resource id is projectId, readable via GET /v1/projects/{id}/.
    messages:
      notificationBatch:
        $ref: '#/components/messages/NotificationBatch'
  listingProcessingReports:
    address: listingProcessingReports
    title: Listing processing reports
    description: >-
      Sent whenever a new listing processing report is available for listings
      submitted through the CRM endpoints. Resource id is reportId, readable via
      GET /v1/listings/processingReports/{id}/.
    messages:
      notificationBatch:
        $ref: '#/components/messages/NotificationBatch'
  heartbeat:
    address: heartbeat
    title: Heartbeat
    description: >-
      Liveness signal for the webhook system, available only to the public group.
      Expect at least one heartbeat notification every 5 minutes.
    messages:
      notificationBatch:
        $ref: '#/components/messages/NotificationBatch'

operations:
  receiveAgencies:
    action: receive
    channel: {$ref: '#/channels/agencies'}
    summary: Receive agency change notifications.
  receiveAgents:
    action: receive
    channel: {$ref: '#/channels/agents'}
    summary: Receive agent change notifications.
  receiveEnquiries:
    action: receive
    channel: {$ref: '#/channels/enquiries'}
    summary: Receive enquiry notifications.
  receiveListings:
    action: receive
    channel: {$ref: '#/channels/listings'}
    summary: Receive listing create/update/delete notifications.
  receiveProjects:
    action: receive
    channel: {$ref: '#/channels/projects'}
    summary: Receive project create/update/delete notifications.
  receiveListingProcessingReports:
    action: receive
    channel: {$ref: '#/channels/listingProcessingReports'}
    summary: Receive listing processing report notifications.
  receiveHeartbeat:
    action: receive
    channel: {$ref: '#/channels/heartbeat'}
    summary: Receive the webhook-system heartbeat.

components:
  messages:
    NotificationBatch:
      name: notificationBatch
      title: Domain notification batch
      summary: >-
        A batch of one or more notifications POSTed to the consumer endpoint. The
        posted entity is always an array, even when only a single notification is
        sent. The consumer must respond 204 No Content, ideally within 2 seconds,
        and process asynchronously.
      contentType: application/json
      headers:
        $ref: '#/components/schemas/NotificationHeaders'
      payload:
        $ref: '#/components/schemas/NotificationBatchPayload'
      examples:
        - name: enquiryNotification
          summary: Example enquiries webhook notification (verbatim from the Processing Notifications guide)
          headers:
            X-Domain-Signature: 0a0430a0a9ace889f9
          payload:
            - resourceType: enquiries
              resourceId: 2014135780-uJfqDDxas-KqBaKC9vypZw==
              date: '2018-01-31T14:59:27.9479833+11:00'
              subscriptionId: 5d76dae5edaf4c47beb66aad4ec5374b
              ownerId: '12345'
              ownerType: agency
              notificationId: 58f1cde3-ad7c-420e-8686-b94db841a930
              isDeleted: false

  schemas:
    NotificationHeaders:
      type: object
      properties:
        X-Domain-Signature:
          type: string
          description: >-
            Lowercase hex HMAC-SHA1 of the raw notification body, keyed on the
            webhook's Verification Code. Consumers should recompute and compare;
            on mismatch, discard the message and return 404.
      required: [X-Domain-Signature]

    NotificationBatchPayload:
      type: array
      description: Batch of notifications.
      items:
        $ref: '#/components/schemas/Notification'

    Notification:
      type: object
      properties:
        resourceType:
          type: string
          description: The subscribed resource type.
          enum:
            - agencies
            - agents
            - enquiries
            - listings
            - projects
            - listingProcessingReports
            - heartbeat
        resourceId:
          type: string
          description: >-
            Identifier of the changed resource, usable on the resource type's
            matching GET endpoint. For heartbeat this is a unique guid.
        date:
          type: string
          format: date-time
          description: When the event occurred.
        subscriptionId:
          type: string
          description: Identifier of the subscription that produced this notification.
        ownerId:
          type: string
          description: >-
            Owner filter identifier - "public" for the group owner type, an
            agency id, or a provider id.
        ownerType:
          type: string
          description: The owner type the subscription filters on.
          enum: [group, agency, provider]
        notificationId:
          type: string
          format: uuid
          description: Unique identifier for this notification.
        isDeleted:
          type: boolean
          description: Whether the referenced resource was deleted.
      required:
        - resourceType
        - resourceId
        - date
        - subscriptionId
        - ownerId
        - ownerType
        - notificationId

x-apievangelist:
  method: generated
  generated: '2026-07-26'
  source: https://developer.domain.com.au/docs/latest/apis/pkg_webhooks
  catalog: asyncapi/domain-group-webhooks.yml
  note: >-
    Provider-published AsyncAPI does not exist. This document is a faithful
    AsyncAPI 3.0.0 rendering of Domain's published webhook catalog and
    notification format; the channel set, payload fields, signature header and
    the single example are taken verbatim from Domain's documentation.
  subscription_management: >-
    Channels here correspond to Domain "resourceType" values. Subscriptions are
    created out-of-band over REST with
    PUT /v1/webhooks/{id}/subscriptions carrying {resourceType, ownerType, ownerId}.