openapi: 3.0.3
info:
  title: HoneyBook API (Modeled) Clients Webhooks API
  description: HoneyBook does not publish a self-serve public developer API or a public API reference. This document models the logical resource surface implied by HoneyBook's product (clients/leads, projects, contracts, proposals, invoices, payments, scheduler sessions) and by the trigger/action events exposed through its Zapier integration (New Client, New Inquiry, Project Booked, Payment Received, Project Stage Changed). An internal API host, https://api.honeybook.com, is live behind Cloudflare and clearly backs HoneyBook's own web/mobile apps and its native integrations, but HoneyBook has never published endpoint documentation, a client registration/OAuth flow, or a field dictionary for outside developers. Third-party integration guides (e.g. Rollout) reference an OAuth 2.0 flow against api.honeybook.com and a `/v1/` base path, but are inconsistent with each other on the exact token endpoint and grant type, and are not independently verifiable - treat every path, parameter, and schema below as an honest, sourced-but-unverified model, not a confirmed reference. Confirm directly with HoneyBook before attempting integration.
  version: 1.0-modeled
  contact:
    name: HoneyBook
    url: https://www.honeybook.com
servers:
- url: https://api.honeybook.com/v1
  description: Modeled base path (unverified; not publicly documented by HoneyBook)
security:
- oauth2: []
tags:
- name: Webhooks
  description: Modeled event subscription surface mirroring HoneyBook's Zapier triggers.
paths:
  /webhooks:
    get:
      operationId: listWebhooks
      tags:
      - Webhooks
      summary: List webhook subscriptions
      description: Not a confirmed HoneyBook capability - modeled for completeness to mirror the five events HoneyBook exposes only as Zapier triggers (New Client, New Inquiry, Project Booked, Payment Received, Project Stage Changed). No public webhook subscription endpoint is documented by HoneyBook.
      responses:
        '200':
          description: A list of webhook subscriptions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWebhook
      tags:
      - Webhooks
      summary: Subscribe to an event
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInput'
      responses:
        '201':
          description: The created webhook subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /webhooks/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    delete:
      operationId: deleteWebhook
      tags:
      - Webhooks
      summary: Delete a webhook subscription
      responses:
        '200':
          description: Deletion confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    DeleteResponse:
      type: object
      properties:
        id:
          type: string
        deleted:
          type: boolean
    Webhook:
      allOf:
      - $ref: '#/components/schemas/WebhookInput'
      - type: object
        properties:
          id:
            type: string
    WebhookInput:
      type: object
      required:
      - event
      - target_url
      properties:
        event:
          type: string
          enum:
          - client.created
          - inquiry.created
          - project.booked
          - payment.paid
          - project.stage_changed
        target_url:
          type: string
          format: uri
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
  responses:
    Unauthorized:
      description: Missing or invalid access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource.
      schema:
        type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: Third-party integration guides reference OAuth 2.0 against api.honeybook.com, but are inconsistent on the exact token endpoint and grant type and are not independently verifiable. Modeled here as an authorization-code flow with refresh tokens, the most common pattern for a user-data platform of this kind; treat as unverified.
      flows:
        authorizationCode:
          authorizationUrl: https://api.honeybook.com/oauth/authorize
          tokenUrl: https://api.honeybook.com/oauth/token
          scopes:
            clients.read: Read clients and inquiries.
            clients.write: Create and update clients and inquiries.
            projects.read: Read projects and pipeline stage.
            projects.write: Create and update projects.
            contracts.read: Read contracts.
            contracts.write: Create contracts.
            proposals.read: Read proposals.
            proposals.write: Create proposals.
            invoices.read: Read invoices.
            invoices.write: Create invoices.
            payments.read: Read payments.
            scheduler.read: Read session types and bookings.
            scheduler.write: Create bookings.
            webhooks.write: Manage webhook subscriptions.
externalDocs:
  description: HoneyBook integrations and partnerships help center
  url: https://help.honeybook.com/en/collections/68941-integrations-and-partnerships