openapi: 3.1.0
info:
  title: 'Web Hook Box API'
  description: "Create webhook endpoints, inspect the requests they capture, and replay them.\n\nAuthentication: send `Authorization: Bearer <api token>`. Generate a token from\nthe account page in the web UI. A token grants full read and write access to that\naccount's webhooks and captured requests.\n\nIdentifiers are ULIDs in Crockford base32, for example `01ARZ3NDEKTSV4RRFFQ69G5FAV`.\n"
  version: 1.0.0
servers:
  -
    url: 'https://webhook-box.com'
    description: 'Web Hook Box'
paths:
  '/webhook/{id}':
    post:
      tags:
        - Receiver
      summary: 'Deliver a payload to a webhook endpoint'
      description: "The receiving endpoint. Any HTTP method is accepted; the request is stored\nverbatim, including headers, query string, and the exact original body.\nRequires no authentication — the ULID in the path is the credential.\n"
      parameters:
        -
          name: id
          in: path
          description: "The webhook's ULID."
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: "Payload stored. Body and status follow the webhook's custom response configuration when one is set."
      security: []
  /api/webhooks:
    get:
      tags:
        - Webhooks
      operationId: get_api_webhook_list
      parameters:
        -
          name: page
          in: query
          description: 'Page number, 1-based.'
          schema:
            type: integer
            default: 1
        -
          name: limit
          in: query
          description: 'Items per page, maximum 100.'
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: "A page of the authenticated user's webhooks."
          content:
            application/json:
              schema:
                properties:
                  items: { type: array, items: { $ref: '#/components/schemas/Webhook' } }
                  total: { type: integer }
                  page: { type: integer }
                  limit: { type: integer }
                type: object
    post:
      tags:
        - Webhooks
      operationId: post_api_webhook_create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '201':
          description: 'Webhook created.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '422':
          description: 'Validation failed.'
  '/api/webhooks/{uuid}':
    get:
      tags:
        - Webhooks
      operationId: get_api_webhook_show
      parameters:
        -
          name: uuid
          in: path
          description: 'Webhook ULID.'
          required: true
          schema:
            type: string
      responses:
        default:
          description: ''
    put:
      tags:
        - Webhooks
      operationId: put_api_webhook_update
      parameters:
        -
          name: uuid
          in: path
          description: 'Webhook ULID.'
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookRequest'
      responses:
        default:
          description: ''
    delete:
      tags:
        - Webhooks
      operationId: delete_api_webhook_delete
      parameters:
        -
          name: uuid
          in: path
          description: 'Webhook ULID.'
          required: true
          schema:
            type: string
      responses:
        '204':
          description: 'Webhook deleted.'
  '/api/webhooks/{uuid}/requests':
    get:
      tags:
        - Requests
      summary: 'List all requests for a webhook endpoint'
      operationId: get_api_webhook_request_list
      parameters:
        -
          name: uuid
          in: path
          description: 'Webhook ULID.'
          required: true
          schema:
            type: string
      responses:
        default:
          description: ''
  '/api/webhooks/{uuid}/requests/{requestUuid}':
    get:
      tags:
        - Requests
      summary: 'Get details of a specific request'
      operationId: get_api_webhook_request_show
      parameters:
        -
          name: uuid
          in: path
          description: 'Webhook ULID.'
          required: true
          schema:
            type: string
        -
          name: requestUuid
          in: path
          description: 'Captured request ULID.'
          required: true
          schema:
            type: string
      responses:
        default:
          description: ''
  '/api/webhooks/{uuid}/requests/{requestUuid}/replay':
    post:
      tags:
        - Requests
      summary: 'Replay a webhook request'
      operationId: post_api_webhook_request_replay
      parameters:
        -
          name: uuid
          in: path
          description: 'Webhook ULID.'
          required: true
          schema:
            type: string
        -
          name: requestUuid
          in: path
          description: 'Captured request ULID.'
          required: true
          schema:
            type: string
      responses:
        default:
          description: ''
  '/api/webhooks/{uuid}/requests/download/json':
    get:
      tags:
        - Requests
      summary: 'Download requests as JSON'
      operationId: get_api_webhook_request_download_json
      parameters:
        -
          name: uuid
          in: path
          description: 'Webhook ULID.'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "JSON export of the webhook's captured requests."
          content:
            application/json: {  }
  '/api/webhooks/{uuid}/requests/download/csv':
    get:
      tags:
        - Requests
      summary: 'Download requests as CSV'
      operationId: get_api_webhook_request_download_csv
      parameters:
        -
          name: uuid
          in: path
          description: 'Webhook ULID.'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "CSV export of the webhook's captured requests."
          content:
            text/csv: {  }
  '/api/webhooks/{uuid}/requests/{requestUuid}/curl':
    get:
      tags:
        - Requests
      summary: 'Get cURL representation of a request'
      operationId: get_api_webhook_request_curl
      parameters:
        -
          name: uuid
          in: path
          description: 'Webhook ULID.'
          required: true
          schema:
            type: string
        -
          name: requestUuid
          in: path
          description: 'Captured request ULID.'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'The captured request rendered as a runnable curl command.'
          content:
            application/json:
              schema:
                properties:
                  command: { type: string }
                type: object
components:
  schemas:
    WebhookResponseDto:
      properties:
        statusCode:
          title: 'HTTP status code for the response'
          type:
            - integer
            - 'null'
          default: 200
          maximum: 599
          minimum: 100
        headers:
          title: 'HTTP headers for the response'
          type: object
          default: []
          additionalProperties:
            type: array
            items:
              type: string
        body:
          title: 'Response body content'
          type:
            - string
            - 'null'
        delay:
          title: 'Delay in seconds before sending the response'
          type: integer
          default: 0
          maximum: 10
          minimum: 0
      type: object
    CreateWebhookRequest:
      properties:
        description:
          title: 'Optional description of the webhook'
          type:
            - string
            - 'null'
          maxLength: 255
        defaultResponse:
          title: 'Optional custom response configuration'
          oneOf:
            -
              $ref: '#/components/schemas/WebhookResponseDto'
            -
              type: 'null'
        forwardUrl:
          title: 'URL to forward webhook requests to'
          type:
            - string
            - 'null'
        enableForwarding:
          title: 'Whether to enable forwarding of webhook requests'
          type: boolean
          default: false
      type: object
    UpdateWebhookRequest:
      properties:
        url:
          title: 'Updated URL of the webhook endpoint'
          type:
            - string
            - 'null'
        description:
          title: 'Updated description of the webhook'
          type:
            - string
            - 'null'
          maxLength: 255
        isActive:
          title: 'Whether the webhook is active'
          type:
            - boolean
            - 'null'
        response:
          title: 'Optional custom response configuration'
          oneOf:
            -
              $ref: '#/components/schemas/WebhookResponseDto'
            -
              type: 'null'
        forwardUrl:
          title: 'URL to forward webhook requests to'
          type:
            - string
            - 'null'
        enableForwarding:
          title: 'Whether to enable forwarding of webhook requests'
          type:
            - boolean
            - 'null'
      type: object
    WebhookResponse:
      required:
        - statusCode
      properties:
        id:
          type:
            - string
            - 'null'
          format: ulid
        statusCode:
          type: integer
        headers:
          type: object
          default: []
          additionalProperties:
            type: array
            items:
              type: string
        body:
          type:
            - string
            - 'null'
        delay:
          type: integer
          default: 0
      type: object
    Webhook:
      required:
        - id
        - createdAt
      properties:
        id:
          type: string
          format: ulid
        description:
          type:
            - string
            - 'null'
        createdAt:
          type: string
          format: date-time
        webhookResponse:
          oneOf:
            -
              $ref: '#/components/schemas/WebhookResponse'
            -
              type: 'null'
        forwardUrl:
          type:
            - string
            - 'null'
        enableForwarding:
          type: boolean
          default: false
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      description: 'An API token generated from the Web Hook Box account page.'
      scheme: bearer
security:
  -
    bearerAuth: []
tags:
  -
    name: Webhooks
  -
    name: Requests
  -
    name: Receiver
    description: Receiver