openapi: 3.2.0
info:
  title: Hookbase Destinations API
  version: 1.0.0
  description: Official OpenAPI 3.0 specification for the Hookbase webhook relay platform. Generated from the maintained Postman collection. Authenticate with an API key (whr_ prefix) as a Bearer token.
  contact:
    name: Hookbase
    url: https://www.hookbase.app
servers:
- url: https://api.hookbase.app
  description: Production
security:
- bearerAuth: []
tags:
- name: Destinations
paths:
  /api/destinations:
    post:
      tags:
      - Destinations
      summary: Create destination
      operationId: destinations_create_destination
      responses:
        '200':
          description: Successful response
      description: Create an outbound destination (HTTP endpoint or warehouse/queue sink).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Required. Display name (1–100 chars).
                slug:
                  type: string
                  description: Required. URL-safe id (1–50 chars, [a-z0-9-]).
                url:
                  type: string
                  description: Optional. Target URL (required for http type; omit/empty for warehouse types).
                method:
                  type: string
                  description: Optional. POST | PUT | PATCH (default POST).
                headers:
                  type: object
                  description: Optional. Static headers sent with each delivery.
                authType:
                  type: string
                  description: Optional. none | basic | bearer | api_key | custom_header.
                authConfig:
                  type: object
                  description: Optional. Credentials keyed by authType — bearer:{token}, basic:{username,password}, api_key/custom_header:{headerName,headerValue}.
                timeoutMs:
                  type: integer
                  description: Optional. Request timeout ms (1000–60000, default 30000).
                throttle:
                  type: object
                  description: 'Optional (default { mode: "off" }). Delivery throttle for this destination.'
                  properties:
                    mode:
                      type: string
                      enum:
                      - 'off'
                      - rate
                      - concurrency
                      description: off = unthrottled. rate requires rateLimit + rateUnit. concurrency requires maxConcurrency.
                    rateLimit:
                      type: integer
                      description: Required when mode is "rate". Max deliveries per rateUnit.
                    rateUnit:
                      type: string
                      enum:
                      - second
                      - minute
                      - hour
                      description: Required when mode is "rate".
                    maxConcurrency:
                      type: integer
                      description: Required when mode is "concurrency". Max deliveries in flight at once.
                    queueLimit:
                      type: integer
                      description: Optional in rate or concurrency mode. Backpressure queue-depth threshold.
                type:
                  type: string
                  description: Optional. http | sqs | eventbridge | servicebus | pubsub | oci_queue | s3 | r2 | gcs | azure_blob (default http).
                config:
                  type: object
                  description: Optional. Provider-specific config for warehouse/queue destination types.
                batchSize:
                  type: integer
                  description: Optional. Events per batch (1–1000, default 1).
                batchWindowSeconds:
                  type: integer
                  description: Optional. Max seconds to wait while batching (0–300, default 0).
                fieldMapping:
                  type: array
                  items:
                    type: object
                  description: 'Optional. Warehouse field mapping (max 50); each { source, target, type: string|number|boolean|timestamp|json, default? }.'
                useStaticIp:
                  type: boolean
                  description: Optional. Route deliveries through a dedicated static IP.
              required:
              - name
              - slug
            example:
              name: Production API
              slug: production-api
              url: https://api.example.com/webhooks
              method: POST
              headers:
                X-Api-Version: 2024-01
              authType: bearer
              authConfig:
                token: secret
              timeoutMs: 30000
              throttle:
                mode: rate
                rateLimit: 600
                rateUnit: minute
              type: http
              config: {}
              batchSize: 1
              batchWindowSeconds: 0
              fieldMapping:
              - source: data.id
                target: id
                type: string
              useStaticIp: false
    get:
      tags:
      - Destinations
      summary: List destinations
      operationId: destinations_list_destinations
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: string
        example: '1'
      - name: pageSize
        in: query
        required: false
        schema:
          type: string
        example: '20'
      responses:
        '200':
          description: Successful response
      description: List destinations for the org (paginated).
  /api/destinations/{destinationId}:
    get:
      tags:
      - Destinations
      summary: Get destination by id
      operationId: destinations_get_destination_by_id
      parameters:
      - name: destinationId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
      description: Fetch a single destination by id or slug (auth config masked).
    patch:
      tags:
      - Destinations
      summary: Update destination
      operationId: destinations_update_destination
      parameters:
      - name: destinationId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
      description: Update a destination. All fields optional.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Optional. Display name.
                url:
                  type: string
                  description: Optional. Target URL.
                method:
                  type: string
                  description: Optional. POST | PUT | PATCH.
                headers:
                  type: object
                  description: Optional. Static headers.
                authType:
                  type: string
                  description: Optional. none | basic | bearer | api_key | custom_header.
                authConfig:
                  type: object
                  description: Optional. Credentials keyed by authType.
                timeoutMs:
                  type: integer
                  description: Optional. Timeout ms (1000–60000).
                throttle:
                  type: object
                  description: Optional. Delivery throttle for this destination.
                  properties:
                    mode:
                      type: string
                      enum:
                      - 'off'
                      - rate
                      - concurrency
                      description: off = unthrottled. rate requires rateLimit + rateUnit. concurrency requires maxConcurrency.
                    rateLimit:
                      type: integer
                      description: Required when mode is "rate". Max deliveries per rateUnit.
                    rateUnit:
                      type: string
                      enum:
                      - second
                      - minute
                      - hour
                      description: Required when mode is "rate".
                    maxConcurrency:
                      type: integer
                      description: Required when mode is "concurrency". Max deliveries in flight at once.
                    queueLimit:
                      type: integer
                      description: Optional in rate or concurrency mode. Backpressure queue-depth threshold.
                type:
                  type: string
                  description: Optional. Destination type.
                config:
                  type: object
                  description: Optional. Provider-specific config.
                batchSize:
                  type: integer
                  description: Optional. Events per batch (1–1000).
                batchWindowSeconds:
                  type: integer
                  description: Optional. Batch window seconds (0–300).
                fieldMapping:
                  type: array
                  items:
                    type: object
                  description: Optional. Warehouse field mapping (max 50).
                useStaticIp:
                  type: boolean
                  description: Optional. Use static IP delivery.
                isActive:
                  type: boolean
                  description: Optional. Enable/disable the destination.
            example:
              name: Production API
              url: https://api.example.com/webhooks
              method: POST
              headers:
                X-Api-Version: 2024-01
              authType: bearer
              authConfig:
                token: secret
              timeoutMs: 30000
              throttle:
                mode: rate
                rateLimit: 600
                rateUnit: minute
              type: http
              config: {}
              batchSize: 1
              batchWindowSeconds: 0
              fieldMapping:
              - source: data.id
                target: id
                type: string
              useStaticIp: false
              isActive: true
  /api/destinations/{destinationId}/test:
    post:
      tags:
      - Destinations
      summary: Test destination
      operationId: destinations_test_destination
      parameters:
      - name: destinationId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
      description: Send a test delivery to the destination to verify connectivity and auth.
  /api/destinations/export:
    get:
      tags:
      - Destinations
      summary: Export destinations
      operationId: destinations_export_destinations
      parameters:
      - name: includeSensitive
        in: query
        required: false
        schema:
          type: string
        example: 'false'
      responses:
        '200':
          description: Successful response
      description: Export all destinations (or ?ids=) as a portable JSON config document.
  /api/destinations/import:
    post:
      tags:
      - Destinations
      summary: Import destinations
      operationId: destinations_import_destinations
      responses:
        '200':
          description: Successful response
      description: Import destinations from the export format.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                destinations:
                  type: array
                  items:
                    type: object
                  description: Required. Array of destination configs in the /export shape.
                conflictStrategy:
                  type: string
                  description: 'Required. On existing slug: skip | rename | overwrite.'
                validateOnly:
                  type: boolean
                  description: Optional. Validate without persisting.
              required:
              - destinations
              - conflictStrategy
            example:
              destinations:
              - name: Production API
                slug: production-api
                url: https://api.example.com/webhooks
              conflictStrategy: skip
              validateOnly: false
  /api/destinations/bulk:
    delete:
      tags:
      - Destinations
      summary: Bulk delete destinations
      operationId: destinations_bulk_delete_destinations
      responses:
        '200':
          description: Successful response
      description: Delete multiple destinations by id (max 100).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: string
                  description: Required. Destination ids to delete (max 100).
              required:
              - ids
            example:
              ids:
              - '{{destinationId}}'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Hookbase API key with the whr_ prefix.