openapi: 3.0.3
info:
  title: At-Bay Partner Documents Webhooks API
  version: '2.0'
  description: REST API for At-Bay's quote-to-bind-to-renew workflow across Surplus Cyber (CYB), Surplus Tech E&O (TEO), and Surplus Miscellaneous Professional Liability (MPL). Authenticated with a JWT bearer token. Quote creation is asynchronous — POST /quotes returns a quote_identifier that is polled via GET /quotes/{quote_identifier} every ~10 seconds until the status leaves `quote_pending`. Production submissions are subject to At-Bay's Broker-of-Record (BOR) clearance process; the demo host bypasses BOR.
  contact:
    name: At-Bay Partnerships
    email: partnerships@at-bay.com
    url: https://developers.at-bay.com
  termsOfService: https://www.at-bay.com/legal/
servers:
- url: https://api.at-bay.com/v2
  description: Production
- url: https://api-demo.at-bay.com/v2
  description: Demo
security:
- bearerAuth: []
tags:
- name: Webhooks
  description: Register webhook endpoints for asynchronous status callbacks.
paths:
  /webhooks:
    get:
      tags:
      - Webhooks
      summary: List Webhooks
      description: Get information about registered webhooks for the partner.
      operationId: listWebhooks
      responses:
        '200':
          description: Registered webhooks.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
    post:
      tags:
      - Webhooks
      summary: Register A Webhook
      description: Register a callback URL for asynchronous quote and policy status events.
      operationId: registerWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRegistration'
      responses:
        '201':
          description: Webhook registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
  /webhooks/{webhook_id}:
    delete:
      tags:
      - Webhooks
      summary: Unregister A Webhook
      description: Remove a previously registered webhook.
      operationId: unregisterWebhook
      parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Webhook removed.
  /webhooks/secret:
    put:
      tags:
      - Webhooks
      summary: Set Webhook Secret
      description: Rotate or set the shared secret used to sign webhook callbacks.
      operationId: setWebhookSecret
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                secret:
                  type: string
      responses:
        '200':
          description: Secret updated.
components:
  schemas:
    WebhookRegistration:
      type: object
      required:
      - url
      - events
      properties:
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
            description: e.g. quote.updated, quote.bound, policy.activated, policy.expired.
    Webhook:
      type: object
      properties:
        webhook_id:
          type: string
        url:
          type: string
        events:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT