RealSelf Lead Sharing

# generated: '2026-08-26'
# method: derived
# source: >-
#   https://api.realself.com/v1/schemas/leads/new-lead-webhook/1-0-0.json (payload contract,
#   served 200 by RealSelf) and https://github.com/RealSelf/rs-lead-sharing-subscriber-example
#   (RealSelf's own subscriber reference implementation, which documents the SNS delivery,
#   the SubscriptionConfirmation handshake and the signature-validation requirement).
#   RealSelf publishes no AsyncAPI document of its own; this description was derived by
#   API Evangelist from the two artifacts above. No channel, field or semantic here is
#   invented — every property comes from the published JSON Schema, and every header and
#   handshake step from RealSelf's published README.
asyncapi: 3.0.0
info:
  title: RealSelf Lead Sharing
  version: 1.0.0
  description: >-
    Event surface RealSelf exposes to partner practices, practice-management systems and
    lead-routing vendors. When a consumer submits a consultation request on realself.com,
    RealSelf publishes a New Lead Webhook notification to an Amazon SNS topic; each partner
    subscribes an HTTPS endpoint to that topic. The subscriber confirms once via the SNS
    SubscriptionConfirmation handshake, then receives Notification messages whose `Message`
    property is a JSON-stringified New Lead payload plus a `callback` URL and a JWS `token`
    for posting lead updates back to RealSelf.
  contact:
    name: RealSelf
    url: https://github.com/RealSelf/rs-lead-sharing-subscriber-example
    email: contactus@realself.com
  termsOfService: https://www.realself.com/terms-of-service
  license:
    name: MIT
    url: https://github.com/RealSelf/rs-lead-sharing-subscriber-example/blob/main/LICENSE.md
  x-derived-by: API Evangelist
  x-provider-published: false
servers:
  sns:
    host: sns.us-west-2.amazonaws.com
    protocol: https
    protocolVersion: '1.1'
    description: >-
      Amazon SNS in us-west-2 fans the notification out to each subscribed partner endpoint.
      Observed topic ARN prefix in RealSelf's published example:
      arn:aws:sns:us-west-2:696689688494:rs-lead-sharing-*.
  subscriber:
    host: '{subscriberHost}'
    protocol: https
    description: >-
      The partner-operated HTTPS endpoint that receives the SNS POST. RealSelf's reference
      subscriber mounts it at POST /api/Lead; the path is chosen by the partner.
    variables:
      subscriberHost:
        description: Hostname of the partner endpoint registered with RealSelf.
        default: subscriber.example.com
channels:
  leadSharing:
    address: 'arn:aws:sns:us-west-2:{account}:rs-lead-sharing-{partner}'
    title: RealSelf lead sharing topic
    description: >-
      SNS topic RealSelf publishes new leads to. One subscription per partner endpoint.
    servers:
      - $ref: '#/servers/sns'
    messages:
      subscriptionConfirmation:
        $ref: '#/components/messages/SubscriptionConfirmation'
      newLead:
        $ref: '#/components/messages/NewLeadNotification'
operations:
  confirmSubscription:
    action: receive
    channel:
      $ref: '#/channels/leadSharing'
    summary: Confirm the SNS subscription (one time).
    description: >-
      Sent once when the subscription is created. The subscriber must validate the message
      signature and then GET the `SubscribeURL` in the body to activate delivery.
    messages:
      - $ref: '#/channels/leadSharing/messages/subscriptionConfirmation'
  receiveNewLead:
    action: receive
    channel:
      $ref: '#/channels/leadSharing'
    summary: Receive a new patient lead.
    description: >-
      Delivered every time a new lead is created. The subscriber must validate the SNS
      signature before trusting the payload, then JSON-parse the `Message` string into the
      New Lead Webhook object.
    messages:
      - $ref: '#/channels/leadSharing/messages/newLead'
components:
  messages:
    SubscriptionConfirmation:
      name: SubscriptionConfirmation
      title: SNS subscription confirmation
      contentType: text/plain; charset=UTF-8
      headers:
        type: object
        properties:
          x-amz-sns-message-type:
            type: string
            const: SubscriptionConfirmation
          x-amz-sns-message-id:
            type: string
          x-amz-sns-topic-arn:
            type: string
        required: [x-amz-sns-message-type, x-amz-sns-message-id, x-amz-sns-topic-arn]
      payload:
        type: object
        properties:
          Type: { type: string, const: SubscriptionConfirmation }
          MessageId: { type: string }
          Token: { type: string }
          TopicArn: { type: string }
          Message: { type: string }
          SubscribeURL:
            type: string
            format: uri
            description: GET this URL to confirm and activate the subscription.
          Timestamp: { type: string, format: date-time }
          SignatureVersion: { type: string }
          Signature: { type: string }
          SigningCertURL: { type: string, format: uri }
    NewLeadNotification:
      name: NewLeadNotification
      title: New lead notification
      contentType: text/plain; charset=UTF-8
      headers:
        type: object
        properties:
          x-amz-sns-message-type:
            type: string
            const: Notification
          x-amz-sns-message-id:
            type: string
          x-amz-sns-topic-arn:
            type: string
          x-amz-sns-subscription-arn:
            type: string
        required: [x-amz-sns-message-type, x-amz-sns-message-id, x-amz-sns-topic-arn]
      payload:
        type: object
        description: >-
          SNS envelope. The lead itself is a JSON-encoded STRING in `Message`, described by
          the New Lead Webhook JSON Schema RealSelf publishes.
        properties:
          Type: { type: string, const: Notification }
          MessageId: { type: string }
          TopicArn: { type: string }
          Subject: { type: string }
          Message:
            type: string
            description: >-
              JSON-stringified New Lead Webhook document. Contract:
              https://api.realself.com/v1/schemas/leads/new-lead-webhook/1-0-0.json
              (saved verbatim at json-schema/realself-new-lead-webhook-1-0-0.json).
          Timestamp: { type: string, format: date-time }
          SignatureVersion: { type: string }
          Signature: { type: string }
          SigningCertURL: { type: string, format: uri }
          UnsubscribeURL: { type: string, format: uri }
          MessageAttributes: { type: object }
      x-message-schema:
        schemaFormat: application/schema+json;version=draft/2020-12
        url: https://api.realself.com/v1/schemas/leads/new-lead-webhook/1-0-0.json
        file: json-schema/realself-new-lead-webhook-1-0-0.json
  securitySchemes:
    snsMessageSignature:
      type: httpApiKey
      in: header
      name: x-amz-sns-message-type
      description: >-
        SNS signs every message; subscribers verify with the AWS SDK
        (`Message.ParseMessage(...).IsMessageSignatureValid()` in RealSelf's example) against
        the certificate at `SigningCertURL`. Unsigned or invalid messages must be rejected 401.