openapi: 3.0.3
info:
  title: Spruce Public Contacts Webhooks API
  description: 'The Spruce Public API connects a Spruce Health organization to internal tools, electronic health records (EHRs), practice management systems, and other external systems so practices can automate workflows, sync data, and receive real-time events. It is a RESTful API over HTTPS with a base URL of https://api.sprucehealth.com/v1 and Bearer token authentication (Authorization: Bearer <your-token>); tokens are generated by administrators from the "API Access" section of Settings after Spruce Support enables API access for the organization (API access is part of the Communicator plan).


    Grounding note: the base URL and Bearer auth are confirmed from the Spruce developer documentation, and the following paths are confirmed directly from the API reference: GET /contacts, GET /conversations, POST /conversations/{conversationId}/messages, GET /webhooks/endpoints, POST /webhooks/endpoints, and GET /internalendpoints. The remaining paths and all request/response schemas are honestly MODELED from the published operation catalog (developer.sprucehealth.com/llms.txt) and documented behavior; exact request/response bodies should be reconciled against the live reference and the machine-readable OpenAPI Spruce publishes.'
  version: '1.0'
  contact:
    name: Spruce Health
    url: https://developer.sprucehealth.com
  x-endpointsModeled: true
servers:
- url: https://api.sprucehealth.com/v1
  description: Spruce Public API
security:
- bearerAuth: []
tags:
- name: Webhooks
  description: Webhook endpoints for real-time contact / conversation events.
paths:
  /webhooks/endpoints:
    get:
      operationId: listWebhookEndpoints
      tags:
      - Webhooks
      summary: List webhook endpoints
      description: Lists the endpoints an organization has registered for webhooks (secret keys are not returned). Confirmed path.
      responses:
        '200':
          description: Webhook endpoints.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookEndpoint'
    post:
      operationId: createWebhookEndpoint
      tags:
      - Webhooks
      summary: Create a webhook endpoint
      description: Registers a new HTTPS webhook endpoint with a name and destination URL. The response includes a signing secret used to verify event signatures; the endpoint must respond 2XX within 5 seconds. Confirmed path.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointCreate'
      responses:
        '200':
          description: The created webhook endpoint, including its signing secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '403':
          $ref: '#/components/responses/Forbidden'
  /webhooks/endpoints/{endpointId}:
    parameters:
    - name: endpointId
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: webhookEndpoint
      tags:
      - Webhooks
      summary: Get a webhook endpoint
      description: Retrieves a webhook endpoint by ID. Modeled.
      responses:
        '200':
          description: The webhook endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
    delete:
      operationId: deleteWebhookEndpoint
      tags:
      - Webhooks
      summary: Delete a webhook endpoint
      description: Deletes a webhook endpoint. Modeled.
      responses:
        '204':
          description: Webhook endpoint deleted.
  /webhooks/endpoints/{endpointId}/events:
    parameters:
    - name: endpointId
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: listWebhookEndpointEvents
      tags:
      - Webhooks
      summary: List a webhook endpoint's events
      description: Lists the events delivered (or attempted) for a webhook endpoint. Modeled.
      responses:
        '200':
          description: Webhook endpoint events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookEvent'
  /webhooks/endpoints/{endpointId}/paused:
    parameters:
    - name: endpointId
      in: path
      required: true
      schema:
        type: string
    put:
      operationId: modifyWebhookEndpointPaused
      tags:
      - Webhooks
      summary: Pause or resume a webhook endpoint
      description: Pauses or resumes dispatch of events to a webhook endpoint. Modeled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                paused:
                  type: boolean
      responses:
        '200':
          description: The updated webhook endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
components:
  responses:
    Forbidden:
      description: Missing, incorrect, or disabled API token.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
  schemas:
    WebhookEvent:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          description: e.g. contact.created, conversation.updated, conversationItem.created.
        createdAt:
          type: string
          format: date-time
        deliveryStatus:
          type: string
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        url:
          type: string
          format: uri
        secret:
          type: string
          description: Signing secret, returned only on creation.
        paused:
          type: boolean
        events:
          type: array
          items:
            type: string
    WebhookEndpointCreate:
      type: object
      required:
      - name
      - url
      properties:
        name:
          type: string
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Organization API token generated in Settings after Spruce Support enables API access.