openapi: 3.2.0
info:
  title: Hookbase Provider Catalog 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: Provider Catalog
  description: Public catalog of supported webhook providers and their signature/secret rules.
paths:
  /api/catalog/providers:
    get:
      tags:
      - Provider Catalog
      summary: List providers
      operationId: catalog_list_providers
      security: []
      description: Public, no auth. Every provider in the catalog with a signature-verification summary. Use hookbaseProvider as the source provider value.
      parameters:
      - name: category
        in: query
        required: false
        schema:
          type: string
        example: payments
      - name: search
        in: query
        required: false
        schema:
          type: string
        description: Case-insensitive match on name, description and category.
      responses:
        '200':
          description: Providers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  providers:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        category:
                          type: string
                        description:
                          type: string
                        icon:
                          type: string
                        eventTypeCount:
                          type: integer
                        hookbaseProvider:
                          type: string
                          description: Value to send as the source provider.
                        hasSignatureVerification:
                          type: boolean
                        hasIpRanges:
                          type: boolean
                        signatureVerification:
                          $ref: '#/components/schemas/CatalogSignatureVerificationSummary'
                  categories:
                    type: array
                    items:
                      type: string
                  total:
                    type: integer
  /api/catalog/providers/{providerId}:
    get:
      tags:
      - Provider Catalog
      summary: Get provider
      operationId: catalog_get_provider
      security: []
      parameters:
      - name: providerId
        in: path
        required: true
        schema:
          type: string
        description: Catalog provider id (may differ from the source provider value; see hookbaseProvider).
      description: Public, no auth. The full catalog entry, including the signatureVerification block, event types, sample payloads and setup guide.
      responses:
        '200':
          description: The provider.
          content:
            application/json:
              schema:
                type: object
                properties:
                  provider:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      category:
                        type: string
                      description:
                        type: string
                      website:
                        type: string
                      docsUrl:
                        type: string
                      icon:
                        type: string
                      hookbaseProvider:
                        type: string
                      signatureVerification:
                        $ref: '#/components/schemas/CatalogSignatureVerification'
                      eventTypes:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                            description:
                              type: string
                      samplePayloads:
                        type: object
                        additionalProperties: true
                      ipRanges:
                        type:
                        - array
                        - 'null'
                        items:
                          type: string
                      setupGuide:
                        type: array
                        items:
                          type: string
        '404':
          description: Provider not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/catalog/providers/{providerId}/events:
    get:
      tags:
      - Provider Catalog
      summary: Get provider event types
      operationId: catalog_get_provider_events
      security: []
      parameters:
      - name: providerId
        in: path
        required: true
        schema:
          type: string
        description: Catalog provider id (may differ from the source provider value; see hookbaseProvider).
      description: Public, no auth. Event types and sample payloads for one provider.
      responses:
        '200':
          description: Event types.
          content:
            application/json:
              schema:
                type: object
                properties:
                  providerId:
                    type: string
                  providerName:
                    type: string
                  eventTypes:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                        description:
                          type: string
                  samplePayloads:
                    type: object
                    additionalProperties: true
        '404':
          description: Provider not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable reason.
    CatalogSignatureVerificationSummary:
      type:
      - object
      - 'null'
      properties:
        supported:
          type: boolean
        kind:
          type: string
          enum:
          - hmac
          - shared_secret
          - bespoke
          - asymmetric
          description: Verification family. Absent for entries that map to custom.
        secretSource:
          type: string
          enum:
          - provider
          - operator
          - public_key
          - built_in
          - none
          description: 'provider: vendor issues it, paste it. operator: Hookbase generates it when omitted, paste it into the vendor. public_key: paste the vendor public key. built_in: no secret (sending one is a 400). none: vendor does not sign / not verifiable yet.'
        secretLabel:
          type: string
          description: The vendor's name for the credential.
        secretPlaceholder:
          type: string
        secretAfterRegistration:
          type: boolean
          description: Present and true when the vendor issues the secret only after the ingest URL is registered (asana, notion).
    CatalogSignatureVerification:
      type:
      - object
      - 'null'
      properties:
        supported:
          type: boolean
        kind:
          type: string
          enum:
          - hmac
          - shared_secret
          - bespoke
          - asymmetric
          description: Verification family. Absent for entries that map to custom.
        secretSource:
          type: string
          enum:
          - provider
          - operator
          - public_key
          - built_in
          - none
          description: 'provider: vendor issues it, paste it. operator: Hookbase generates it when omitted, paste it into the vendor. public_key: paste the vendor public key. built_in: no secret (sending one is a 400). none: vendor does not sign / not verifiable yet.'
        secretLabel:
          type: string
          description: The vendor's name for the credential.
        secretPlaceholder:
          type: string
        secretAfterRegistration:
          type: boolean
          description: Present and true when the vendor issues the secret only after the ingest URL is registered (asana, notion).
        algorithm:
          type: string
        headerName:
          type: string
        secretLocationHint:
          type: string
        secretInstruction:
          type: string
          description: Where to copy the value from, where to paste a generated one, or why there is nothing to enter.
        secretFormat:
          type: string
          enum:
          - whsec
          - basic_auth
        verifyToken:
          type: object
          description: 'Meta providers (whatsapp) only: the second, Hookbase-generated credential checked at registration.'
          properties:
            label:
              type: string
            instruction:
              type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Hookbase API key with the whr_ prefix.