openapi.yaml

openapi: 3.0.3
info:
  title: Webhooks
  version: WEBHOOKS_VERSION
servers:
  - url: http://localhost:8080/
security:
  - Authorization: []
paths:
  x-speakeasy-errors:
    statusCodes:
      - default
  /configs:
    get:
      summary: Get many configs
      description: Sorted by updated date descending
      operationId: getManyConfigs
      tags:
        - webhooks.v1
      parameters:
        - name: id
          in: query
          description: Optional filter by Config ID
          required: false
          schema:
            type: string
            example: 4997257d-dfb6-445b-929c-cbe2ab182818
        - name: endpoint
          in: query
          description: Optional filter by endpoint URL
          required: false
          schema:
            type: string
            example: https://example.com
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Authorization:
            - webhooks:read
    post:
      summary: Insert a new config
      description: >
        Insert a new webhooks config.


        The endpoint should be a valid https URL and be unique.


        The secret is the endpoint's verification secret.

        If not passed or empty, a secret is automatically generated.

        The format is a random string of bytes of size 24, base64 encoded.
        (larger size after encoding)


        All eventTypes are converted to lower-case when inserted.
      operationId: insertConfig
      tags:
        - webhooks.v1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigUser'
        required: true
      responses:
        '200':
          description: Config created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Authorization:
            - webhooks:write
  /configs/{id}:
    delete:
      summary: Delete one config
      description: Delete a webhooks config by ID.
      operationId: deleteConfig
      tags:
        - webhooks.v1
      parameters:
        - name: id
          in: path
          description: Config ID
          required: true
          schema:
            type: string
            example: 4997257d-dfb6-445b-929c-cbe2ab182818
      responses:
        '200':
          description: Config successfully deleted.
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Authorization:
            - webhooks:write
    put:
      summary: Update one config
      description: Update a webhooks config by ID.
      operationId: updateConfig
      tags:
        - webhooks.v1
      parameters:
        - name: id
          in: path
          description: Config ID
          required: true
          schema:
            type: string
            example: 4997257d-dfb6-445b-929c-cbe2ab182818
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigUser'
        required: true
      responses:
        '200':
          description: Config successfully updated.
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Authorization:
            - webhooks:write
  /configs/{id}/test:
    get:
      summary: Test one config
      description: Test a config by sending a webhook to its endpoint.
      operationId: testConfig
      tags:
        - webhooks.v1
      parameters:
        - name: id
          in: path
          description: Config ID
          required: true
          schema:
            type: string
            example: 4997257d-dfb6-445b-929c-cbe2ab182818
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttemptResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Authorization:
            - webhooks:read
  /configs/{id}/activate:
    put:
      summary: Activate one config
      description: >-
        Activate a webhooks config by ID, to start receiving webhooks to its
        endpoint.
      operationId: activateConfig
      tags:
        - webhooks.v1
      parameters:
        - name: id
          in: path
          description: Config ID
          required: true
          schema:
            type: string
            example: 4997257d-dfb6-445b-929c-cbe2ab182818
      responses:
        '200':
          description: Config successfully activated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Authorization:
            - webhooks:write
  /configs/{id}/deactivate:
    put:
      summary: Deactivate one config
      description: >-
        Deactivate a webhooks config by ID, to stop receiving webhooks to its
        endpoint.
      operationId: deactivateConfig
      tags:
        - webhooks.v1
      parameters:
        - name: id
          in: path
          description: Config ID
          required: true
          schema:
            type: string
            example: 4997257d-dfb6-445b-929c-cbe2ab182818
      responses:
        '200':
          description: Config successfully deactivated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Authorization:
            - webhooks:write
  /configs/{id}/secret/change:
    put:
      summary: Change the signing secret of a config
      description: >
        Change the signing secret of the endpoint of a webhooks config.


        If not passed or empty, a secret is automatically generated.

        The format is a random string of bytes of size 24, base64 encoded.
        (larger size after encoding)
      operationId: changeConfigSecret
      tags:
        - webhooks.v1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigChangeSecret'
      parameters:
        - name: id
          in: path
          description: Config ID
          required: true
          schema:
            type: string
            example: 4997257d-dfb6-445b-929c-cbe2ab182818
      responses:
        '200':
          description: Secret successfully changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Authorization:
            - webhooks:write
  /deliveries:
    get:
      summary: List webhook deliveries
      operationId: getDeliveries
      tags: [webhooks.v1]
      parameters:
        - {name: configId, in: query, schema: {type: string, format: uuid}}
        - {name: status, in: query, schema: {$ref: '#/components/schemas/DeliveryStatus'}}
        - {name: createdAtFrom, in: query, schema: {type: string, format: date-time}}
        - {name: createdAtTo, in: query, schema: {type: string, format: date-time}}
        - {name: cursor, in: query, schema: {type: string}}
        - {name: pageSize, in: query, schema: {type: integer, minimum: 1, maximum: 1000, default: 100}}
      responses:
        '200':
          description: Paginated deliveries without payloads.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/DeliveriesResponse'}
        default:
          description: Error
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorResponse'}
      security:
        - Authorization: [webhooks:read]
  /deliveries/replay:
    post:
      summary: Replay a page of failed or pending deliveries
      operationId: replayDeliveries
      tags: [webhooks.v1]
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema: {type: string, maxLength: 255}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ReplayDeliveriesRequest'}
      responses:
        '200':
          description: Deliveries synchronously placed back in the durable queue.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ReplayDeliveriesResponse'}
        default:
          description: Error
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorResponse'}
      security:
        - Authorization: [webhooks:write]
  /deliveries/{id}:
    get:
      summary: Get a webhook delivery
      operationId: getDelivery
      tags: [webhooks.v1]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200':
          description: Delivery detail including its payload.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/DeliveryResponse'}
        default:
          description: Error
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorResponse'}
      security:
        - Authorization: [webhooks:read]
  /deliveries/{id}/attempts:
    get:
      summary: List attempts for a webhook delivery
      operationId: getDeliveryAttempts
      tags: [webhooks.v1]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
        - {name: cursor, in: query, schema: {type: string}}
        - {name: pageSize, in: query, schema: {type: integer, minimum: 1, maximum: 1000, default: 100}}
      responses:
        '200':
          description: Paginated append-only attempt history.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/DeliveryAttemptsResponse'}
        default:
          description: Error
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorResponse'}
      security:
        - Authorization: [webhooks:read]
  /deliveries/{id}/replay:
    post:
      summary: Replay one failed or pending delivery
      operationId: replayDelivery
      tags: [webhooks.v1]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
        - name: Idempotency-Key
          in: header
          required: true
          schema: {type: string, maxLength: 255}
      responses:
        '200':
          description: Delivery synchronously placed back in the durable queue.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/DeliveryResponse'}
        default:
          description: Error
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorResponse'}
      security:
        - Authorization: [webhooks:write]
components:
  securitySchemes:
    Authorization:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '/oauth/token'
          refreshUrl: '/oauth/token'
          scopes: {}
  schemas:
    DeliveryStatus:
      type: string
      description: Current state of a delivery in its retry lifecycle
      enum: [pending, delivering, succeeded, failed, cancelled]
    Delivery:
      type: object
      description: An event queued for delivery to a webhook endpoint, tracking its retry state
      required: [id, eventID, configID, eventType, status, attemptCount, replayGeneration, createdAt, updatedAt]
      properties:
        id: {type: string, format: uuid, description: "Unique identifier of the delivery"}
        eventID: {type: string, description: "Identifier of the event being delivered"}
        idempotencyKey: {type: string, description: "Key sent with the request so the receiver can deduplicate retries of the same delivery"}
        configID: {type: string, format: uuid, description: "Identifier of the webhook configuration this delivery targets"}
        eventType: {type: string, description: "Type of the event being delivered"}
        payload: {type: string, description: Present only on delivery detail responses.}
        status: {$ref: '#/components/schemas/DeliveryStatus'}
        attemptCount: {type: integer, description: "Number of attempts made in the current retry cycle. Reset when a failed delivery is replayed"}
        replayGeneration: {type: integer, description: "Incremented each time a failed delivery is replayed, grouping attempts into retry cycles. Replaying a pending delivery leaves it unchanged"}
        cycleStartedAt: {type: string, format: date-time, description: "When the current retry cycle began. Cleared when a failed delivery is replayed"}
        nextAttemptAt: {type: string, format: date-time, description: "When the next delivery attempt is scheduled"}
        claimedAt: {type: string, format: date-time, description: "When a worker claimed this delivery for the attempt in flight. Cleared when a failed delivery is replayed"}
        lastAttemptAt: {type: string, format: date-time, description: "When the most recent attempt was made"}
        lastStatusCode: {type: integer, description: "HTTP status code returned by the most recent attempt"}
        lastError: {type: string, description: "Error reported by the most recent attempt"}
        createdAt: {type: string, format: date-time, description: "When the delivery was created"}
        updatedAt: {type: string, format: date-time, description: "When the delivery was last modified"}
    DeliveryAttempt:
      type: object
      required: [id, deliveryID, attemptNumber, replayGeneration, endpoint, outcome, statusCode, createdAt]
      properties:
        id: {type: string, format: uuid, description: "Unique identifier of the attempt"}
        deliveryID: {type: string, format: uuid, description: "Identifier of the delivery this attempt belongs to"}
        attemptNumber: {type: integer, description: "Position of this attempt within its retry cycle"}
        replayGeneration: {type: integer, description: "Retry cycle this attempt belongs to"}
        endpoint: {type: string, format: uri, description: "URL the attempt was sent to"}
        outcome:
          type: string
          description: How the attempt ended. A retryable failure is retried, a permanent failure is not
          enum: [succeeded, retryable_failure, permanent_failure]
        statusCode: {type: integer, description: "HTTP status code returned by the endpoint"}
        error: {type: string, description: "Error reported by the attempt, when it did not succeed"}
        durationMillis: {type: integer, format: int64, description: "How long the attempt took, in milliseconds"}
        responseExcerpt: {type: string, description: "Truncated body returned by the endpoint, kept for troubleshooting"}
        createdAt: {type: string, format: date-time, description: "When the attempt was made"}
    DeliveryResponse:
      type: object
      required: [data]
      properties:
        data: {$ref: '#/components/schemas/Delivery'}
    DeliveriesResponse:
      type: object
      required: [cursor]
      properties:
        cursor:
          type: object
          description: Paginated cursor wrapping the list of deliveries
          required: [hasMore, data]
          properties:
            pageSize: {type: integer}
            hasMore: {type: boolean}
            next: {type: string}
            data:
              type: array
              items: {$ref: '#/components/schemas/Delivery'}
    DeliveryAttemptsResponse:
      type: object
      required: [cursor]
      properties:
        cursor:
          type: object
          description: Paginated cursor wrapping the list of delivery attempts
          required: [hasMore, data]
          properties:
            pageSize: {type: integer}
            hasMore: {type: boolean}
            next: {type: string}
            data:
              type: array
              items: {$ref: '#/components/schemas/DeliveryAttempt'}
    ReplayDeliveriesRequest:
      type: object
      required: [createdAtFrom]
      properties:
        createdAtFrom: {type: string, format: date-time, description: "Replay deliveries created at or after this time"}
        createdAtTo: {type: string, format: date-time, description: "Replay deliveries created at or before this time. Defaults to now when omitted"}
        statuses:
          type: array
          items:
            type: string
            enum: [failed, pending]
          default: [failed, pending]
          description: Restrict the replay to deliveries in these statuses
        configIds:
          type: array
          description: Restrict the replay to deliveries targeting these webhook configurations
          items: {type: string, format: uuid}
        cursor: {type: string, description: "Pagination cursor from a previous replay response, used to continue a large replay"}
        pageSize: {type: integer, minimum: 1, maximum: 1000, default: 1000, description: "Maximum number of deliveries to process in this call"}
    ReplayDeliveriesResult:
      type: object
      description: Outcome of a bulk replay, counting the deliveries it moved
      required: [replayed, expedited, skipped, hasMore, createdAtTo]
      properties:
        replayed: {type: integer, description: "Number of failed deliveries moved back to pending and scheduled for a new retry cycle"}
        expedited: {type: integer, description: "Number of already-pending deliveries whose next attempt was brought forward to now"}
        skipped: {type: integer, description: "Number of candidates left untouched, because their status changed before the replay applied"}
        hasMore: {type: boolean, description: "Whether further deliveries match and can be processed with the returned cursor"}
        nextCursor: {type: string, description: "Cursor to pass to the next replay call to continue where this one stopped"}
        createdAtTo: {type: string, format: date-time, description: "Upper time bound actually applied, echoed so a paginated replay stays on a fixed window"}
    ReplayDeliveriesResponse:
      type: object
      required: [data]
      properties:
        data: {$ref: '#/components/schemas/ReplayDeliveriesResult'}
    ConfigUser:
      type: object
      required:
        - endpoint
        - eventTypes
      properties:
        endpoint:
          type: string
          description: URL events are delivered to
          example: https://example.com
        secret:
          type: string
          description: Secret used to sign delivery payloads. Generated automatically when omitted
          example: V0bivxRWveaoz08afqjU6Ko/jwO0Cb+3
        eventTypes:
          type: array
          description: Types of event that trigger a delivery to this endpoint
          items:
            type: string
            example: TYPE1
          example:
            - TYPE1
            - TYPE2
    ConfigsResponse:
      type: object
      required:
        - cursor
      properties:
        cursor:
          description: Paginated cursor wrapping the list of configurations
          allOf:
            - $ref: '#/components/schemas/Cursor'
            - properties:
                data:
                  items:
                    $ref: '#/components/schemas/WebhooksConfig'
                  type: array
              type: object
              required:
                - data
    Cursor:
      type: object
      required:
        - hasMore
        - data
      properties:
        hasMore:
          type: boolean
          description: Whether further pages are available
          example: false
        data:
          type: array
          description: The configurations on this page
          items:
            $ref: '#/components/schemas/WebhooksConfig'
    ConfigResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/WebhooksConfig'
    WebhooksConfig:
      type: object
      description: A webhook endpoint together with the event types it subscribes to
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the configuration
        endpoint:
          type: string
          description: URL events are delivered to
          example: https://example.com
        secret:
          type: string
          description: Secret used to sign delivery payloads, letting the receiver verify their authenticity
          example: V0bivxRWveaoz08afqjU6Ko/jwO0Cb+3
        eventTypes:
          type: array
          description: Types of event that trigger a delivery to this endpoint
          items:
            type: string
            example: TYPE1
          example:
            - TYPE1
            - TYPE2
        active:
          type: boolean
          description: Whether the configuration is active. Deactivated configurations receive no deliveries
          example: true
        createdAt:
          type: string
          format: date-time
          description: When the configuration was created
        updatedAt:
          type: string
          format: date-time
          description: When the configuration was last modified
      required:
        - id
        - endpoint
        - secret
        - eventTypes
        - active
        - createdAt
        - updatedAt
    ConfigChangeSecret:
      type: object
      properties:
        secret:
          type: string
          description: The new signing secret, 24 random bytes encoded as base64
          example: V0bivxRWveaoz08afqjU6Ko/jwO0Cb+3
      required:
        - secret
    AttemptResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/Attempt'
    Attempt:
      type: object
      description: A single delivery attempt made against a webhook endpoint
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the attempt
        webhookID:
          type: string
          format: uuid
          description: Identifier of the webhook this attempt belongs to
        createdAt:
          type: string
          format: date-time
          description: When the attempt was created
        updatedAt:
          type: string
          format: date-time
          description: When the attempt was last modified
        config:
          $ref: '#/components/schemas/WebhooksConfig'
        payload:
          type: string
          description: The event body sent to the endpoint
          example: '{"data":"test"}'
        statusCode:
          type: integer
          description: HTTP status code returned by the endpoint
          example: 200
        retryAttempt:
          type: integer
          description: Position of this attempt in the retry sequence
          example: 1
        status:
          type: string
          description: Current status of the attempt
          example: success
        nextRetryAfter:
          type: string
          format: date-time
          description: When the next retry is scheduled, absent once the attempt is settled
      required:
        - id
        - webhookID
        - createdAt
        - updatedAt
        - config
        - payload
        - statusCode
        - retryAttempt
        - status
    ErrorResponse:
      type: object
      required:
        - errorCode
        - errorMessage
      properties:
        errorCode:
          $ref: '#/components/schemas/ErrorsEnum'
        errorMessage:
          type: string
          description: Human-readable description of the error
          example: '[VALIDATION] invalid ''cursor'' query param'
        details:
          type: string
          description: Optional link carrying additional context about the error
          example: >-
            https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9
    ErrorsEnum:
      type: string
      description: Machine-readable error code identifying the failure
      enum:
        - INTERNAL
        - VALIDATION
        - NOT_FOUND
        - CONFLICT
      example: VALIDATION