asyncapi: 3.0.0
info:
  title: Stepes Public API Webhooks
  version: 2.0.0
  description: >-
    Signed notifications for quote, project, and delivery changes. Events may
    be retried, so webhook handlers must deduplicate them by event id.
servers:
  customerEndpoint:
    host: customer.example
    protocol: https
    description: The HTTPS endpoint registered through POST /v2/webhooks.
channels:
  clientWebhook:
    address: /registered-webhook-path
    description: Customer-owned callback URL. Redirects and private network targets are rejected.
    messages:
      quoteCreated: {$ref: '#/components/messages/QuoteCreated'}
      quoteUpdated: {$ref: '#/components/messages/QuoteUpdated'}
      quoteSubmitted: {$ref: '#/components/messages/QuoteSubmitted'}
      quoteAccepted: {$ref: '#/components/messages/QuoteAccepted'}
      projectCreated: {$ref: '#/components/messages/ProjectCreated'}
      projectUpdated: {$ref: '#/components/messages/ProjectUpdated'}
      projectCancelled: {$ref: '#/components/messages/ProjectCancelled'}
      projectCompleted: {$ref: '#/components/messages/ProjectCompleted'}
      deliveryReady: {$ref: '#/components/messages/DeliveryReady'}
operations:
  deliverLifecycleEvent:
    action: send
    summary: Deliver a persisted Stepes lifecycle event
    channel:
      $ref: '#/channels/clientWebhook'
    messages:
      - $ref: '#/channels/clientWebhook/messages/quoteCreated'
      - $ref: '#/channels/clientWebhook/messages/quoteUpdated'
      - $ref: '#/channels/clientWebhook/messages/quoteSubmitted'
      - $ref: '#/channels/clientWebhook/messages/quoteAccepted'
      - $ref: '#/channels/clientWebhook/messages/projectCreated'
      - $ref: '#/channels/clientWebhook/messages/projectUpdated'
      - $ref: '#/channels/clientWebhook/messages/projectCancelled'
      - $ref: '#/channels/clientWebhook/messages/projectCompleted'
      - $ref: '#/channels/clientWebhook/messages/deliveryReady'
components:
  messages:
    QuoteCreated:
      name: quote.created
      title: Quote created
      summary: A quote was created.
      x-stepes-category: Quotes
      x-stepes-trigger: A new quote became available after quote or project creation.
      x-stepes-source-operations: [createQuote, createProject]
      x-stepes-schema-version: '1.0'
      contentType: application/json
      headers: {$ref: '#/components/schemas/WebhookHeaders'}
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties: {type: {const: quote.created}}
    QuoteUpdated:
      name: quote.updated
      title: Quote updated
      summary: Quote inputs, pricing, or lifecycle state changed.
      x-stepes-category: Quotes
      x-stepes-trigger: Quote details, pricing, or status changed.
      x-stepes-source-operations: [updateQuote]
      x-stepes-schema-version: '1.0'
      contentType: application/json
      headers: {$ref: '#/components/schemas/WebhookHeaders'}
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties: {type: {const: quote.updated}}
    QuoteSubmitted:
      name: quote.submitted
      title: Quote submitted
      summary: A quote was submitted and can no longer be edited.
      x-stepes-category: Quotes
      x-stepes-trigger: POST /v2/quotes/{quoteId}/submit completed.
      x-stepes-source-operations: [submitQuote]
      x-stepes-schema-version: '1.0'
      contentType: application/json
      headers: {$ref: '#/components/schemas/WebhookHeaders'}
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties: {type: {const: quote.submitted}}
    QuoteAccepted:
      name: quote.accepted
      title: Quote accepted
      summary: A quote was accepted and project creation started.
      x-stepes-category: Quotes
      x-stepes-trigger: Quote acceptance completed and a translation project was created.
      x-stepes-source-operations: [acceptQuote, createProject]
      x-stepes-schema-version: '1.0'
      contentType: application/json
      headers: {$ref: '#/components/schemas/WebhookHeaders'}
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties: {type: {const: quote.accepted}}
    ProjectCreated:
      name: project.created
      title: Project created
      summary: A translation project was created.
      x-stepes-category: Projects
      x-stepes-trigger: POST /v2/projects or quote acceptance created a project.
      x-stepes-source-operations: [createProject, acceptQuote]
      x-stepes-schema-version: '1.0'
      contentType: application/json
      headers: {$ref: '#/components/schemas/WebhookHeaders'}
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties: {type: {const: project.created}}
    ProjectUpdated:
      name: project.updated
      title: Project updated
      summary: Project status, progress, or delivery availability changed.
      x-stepes-category: Projects
      x-stepes-trigger: The project's status, progress, or available results changed.
      x-stepes-source-operations: []
      x-stepes-schema-version: '1.0'
      contentType: application/json
      headers: {$ref: '#/components/schemas/WebhookHeaders'}
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties: {type: {const: project.updated}}
    ProjectCancelled:
      name: project.cancelled
      title: Project cancelled
      summary: A project was cancelled.
      x-stepes-category: Projects
      x-stepes-trigger: A project reached the cancelled state.
      x-stepes-source-operations: [cancelProject]
      x-stepes-schema-version: '1.0'
      contentType: application/json
      headers: {$ref: '#/components/schemas/WebhookHeaders'}
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties: {type: {const: project.cancelled}}
    ProjectCompleted:
      name: project.completed
      title: Project completed
      summary: All requested translations are complete.
      x-stepes-category: Projects
      x-stepes-trigger: The project reached the completed state.
      x-stepes-source-operations: []
      x-stepes-schema-version: '1.0'
      contentType: application/json
      headers: {$ref: '#/components/schemas/WebhookHeaders'}
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties: {type: {const: project.completed}}
    DeliveryReady:
      name: delivery.ready
      title: Delivery ready
      summary: A translated file or structured result is ready.
      x-stepes-category: Deliveries
      x-stepes-trigger: A new project delivery became available for download or retrieval.
      x-stepes-source-operations: []
      x-stepes-schema-version: '1.0'
      contentType: application/json
      headers: {$ref: '#/components/schemas/WebhookHeaders'}
      payload:
        allOf:
          - $ref: '#/components/schemas/EventEnvelope'
          - type: object
            properties: {type: {const: delivery.ready}}
  schemas:
    WebhookHeaders:
      type: object
      additionalProperties: false
      required:
        - Stepes-Webhook-Id
        - Stepes-Webhook-Delivery-Id
        - Stepes-Webhook-Timestamp
        - Stepes-Webhook-Signature
      properties:
        Stepes-Webhook-Id:
          type: string
          pattern: '^evt_'
          description: Stable event identifier used for consumer deduplication.
        Stepes-Webhook-Delivery-Id:
          type: string
          pattern: '^whd_'
          description: Stable delivery identifier for this endpoint and event.
        Stepes-Webhook-Timestamp:
          type: string
          pattern: '^[0-9]+$'
          description: Unix timestamp included in the signed material.
        Stepes-Webhook-Signature:
          type: string
          pattern: '^v1=[a-f0-9]{64}(,v1=[a-f0-9]{64})?$'
    EventType:
      type: string
      enum:
        - quote.created
        - quote.updated
        - quote.submitted
        - quote.accepted
        - project.created
        - project.updated
        - project.cancelled
        - project.completed
        - delivery.ready
    EventEnvelope:
      type: object
      additionalProperties: false
      required: [id, object, type, created_at, data]
      properties:
        id:
          type: string
          pattern: '^evt_'
          description: Stable event ID used for consumer deduplication.
        object: {const: event}
        type: {$ref: '#/components/schemas/EventType'}
        created_at: {type: string, format: date-time}
        data:
          type: object
          additionalProperties: false
          required: [object]
          properties:
            object:
              type: object
              additionalProperties: true
              description: Quote, project, or delivery data using public API fields and IDs.