Joinways Webhooks API

openapi: 3.2.0
info:
  title: Joinways Public Webhooks API
  version: 1.15.0
  description: 'The Joinways REST API lets you read and manage your CRM and event data:

    events, quotes, invoices, companies, contacts, leads (requests), venues,

    catalog, tasks, reports and more. It is a **JSON over HTTPS** API described by

    this OpenAPI 3.1 document, served at `https://joinways.app/openapi.yaml`

    and rendered at `https://joinways.app/docs/api`. The same data is reachable from AI assistants through the Joinways MCP

    server (`https://mcp.joinways.app`, guide at

    `https://joinways.app/docs/claude-mcp`): both surfaces share the OAuth

    server, the tokens, the scopes, the role permissions and the services of

    the app, so a rule holds the same way in the app, in the REST API and in

    MCP. ## Authentication


    Every request needs a **Bearer token** in the `Authorization` header:


    ```

    Authorization: Bearer jw_xxxxxxxx

    ```


    Two token types work:


    - **API key** (`jw_…`): an owner or admin creates one from **Settings →

    Developers → API keys** in the workspace (guide:

    `https://joinways.app/docs/api-keys`). An API key acts as the member

    who created it: it carries the read and write scopes, and the **role

    permissions its creator holds now** in the workspace (see below; a

    creator who leaves the workspace takes the key''s access with them). It

    does not expire unless you set an expiry, and can be revoked at any

    time from the same page. - **OAuth 2.1 access token** (`jw_oat_…`): for apps acting on a user''s

    behalf (Authorization Code + PKCE S256, same flow as the MCP server). - Authorization endpoint `https://joinways.app/oauth/authorize`, token

    endpoint `https://joinways.app/api/oauth/token`, revocation

    `https://joinways.app/api/oauth/revoke` (RFC 7009), metadata

    `https://joinways.app/.well-known/oauth-authorization-server`. - **Clients**: register with Dynamic Client Registration

    (`POST /api/oauth/register`), or use an https URL as `client_id`

    (Client ID Metadata Document). - **Resource** (RFC 8707): send `resource=https://joinways.app/api/v1`

    on the authorization and token requests to bind the token to this API

    (a token bound to `https://mcp.joinways.app` is refused here, and the

    other way round). An unknown resource is refused with

    `invalid_target`. Protected resource metadata:

    `https://joinways.app/.well-known/oauth-protected-resource/api/v1`. - **Refresh**: a client registered with the `refresh_token` grant gets a

    refresh token (`jw_ort_…`) next to a **1 hour** access token. Each

    refresh rotates the refresh token (the old one stops working); a

    refresh token unused for 90 days expires. A client without the

    refresh grant gets a **30 day** access token and re-runs the flow. A refresh may ask for fewer scopes: only the new access token is

    narrowed. A user who left the workspace gets `invalid_grant` on

    refresh, and the whole token family is revoked. - **Granted scope** = requested ∩ supported (`mcp.read`, `mcp.write`)

    ∩ registered by the client. - The authorization response carries `iss` (RFC 9207). The consent

    screen shows the host of a metadata-document client, and warns when

    the `redirect_uri` is on another domain. - A workspace owner sees and revokes connected apps in **Settings →

    Developers → MCP → Connected apps**. A token is **bound to a single workspace**. You never pass an

    `account_id`: the workspace comes from the token. The API is part of

    the **Pro plan and the free trial**: a valid token of a workspace

    without either is refused with `403 forbidden`, `details.reason:

    plan_not_eligible`. Revocation takes effect within about a minute

    across our infrastructure. Tokens are stored hashed (SHA-256) and shown

    once. A `401` carries the RFC 6750 / RFC 9728 challenge:


    ```

    WWW-Authenticate: Bearer resource_metadata="https://joinways.app/.well-known/oauth-protected-resource/api/v1", scope="mcp.read mcp.write"

    ```


    ## Scopes


    | Scope | Grants |

    |---|---|

    | `mcp.read` | Every `GET` |

    | `mcp.write` | Every `POST`, `PATCH`, `PUT`, `DELETE`, and reading (it implies `mcp.read`) |


    API keys carry both scopes.'
  contact:
    name: Joinways
    url: https://joinways.app
  license:
    name: Proprietary
  x-logo:
    url: /images/marketing/logo-header.svg
    altText: Joinways
    href: https://joinways.app
servers:
- url: https://joinways.app/api/v1
  description: Production
security:
- bearerAuth: []
- oauth2:
  - mcp.read
  - mcp.write
tags:
- name: Webhooks
paths:
  /webhooks:
    get:
      tags:
      - Webhooks
      summary: List webhook subscriptions
      operationId: listWebhookSubscriptions
      description: The workspace's outbound webhook subscriptions, newest first. The signing secret is never returned after creation; without `integrations.manage`, `target_url` is reduced to its origin (`https://hooks.example.com/…`). Not paginated. **Role permission:** none (any member).
      security:
      - bearerAuth: []
      - oauth2:
        - mcp.read
      responses:
        '200':
          description: Webhook subscriptions.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookSubscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      tags:
      - Webhooks
      summary: Create a webhook subscription
      operationId: createWebhookSubscription
      description: 'Subscribes a public https endpoint to events (Zapier REST Hooks contract). The `secret` (`whsec_…`) is returned only here: keep it to check the signatures. Delivery format, headers, signature and retries are described in the **Webhooks** section above. At most 25 active subscriptions per workspace. **Role permission:** `integrations.manage`.'
      security:
      - bearerAuth: []
      - oauth2:
        - mcp.write
      x-required-permission: integrations.manage
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - target_url
              - event_types
              properties:
                target_url:
                  type: string
                  format: uri
                  maxLength: 2048
                  description: Public https endpoint that receives the deliveries.
                event_types:
                  type: array
                  minItems: 1
                  items:
                    $ref: '#/components/schemas/WebhookEventType'
                source:
                  type: string
                  enum:
                  - zapier
                  - custom
                  default: custom
            example:
              target_url: https://hooks.example.com/joinways
              event_types:
              - lead.created
              - event.status_changed
      responses:
        '201':
          description: Subscription created. `secret` is only returned here.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WebhookSubscription'
                - type: object
                  required:
                  - secret
                  properties:
                    secret:
                      type: string
                      example: whsec_3f9a…
        '400':
          $ref: '#/components/responses/BadRequest'
          description: Validation failed, or `target_url` is not a public https URL.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: Active subscription quota reached (`quota_exceeded`, 25 per workspace).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
  /webhooks/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    delete:
      tags:
      - Webhooks
      summary: Delete a webhook subscription
      operationId: deleteWebhookSubscription
      description: Zapier `performUnsubscribe`. The member who created the hook may always delete it; any other hook of the workspace needs `integrations.manage` (`403` otherwise). An unknown id is a success (idempotent). **Role permission:** `data.write` (own hook) or `integrations.manage`.
      security:
      - bearerAuth: []
      - oauth2:
        - mcp.write
      x-required-permission: data.write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Deleted, or already gone.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
          description: '`id` is not a UUID (an unknown UUID is a success).'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  headers:
    RateLimitLimit:
      description: Requests allowed in the current window (per workspace once authenticated, per IP before).
      schema:
        type: integer
        example: 600
    RateLimitReset:
      description: When the window resets (ISO 8601).
      schema:
        type: string
        format: date-time
        example: '2026-10-04T14:31:00.000Z'
    RateLimitRemaining:
      description: Requests left in the current window.
      schema:
        type: integer
        example: 0
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        example: 12
  schemas:
    LeadErrorReason:
      type: string
      description: 'Leads: convert, merge, link, status, create.'
      enum:
      - lead_not_found
      - lead_locked
      - invalid_venue
      - invalid_dates
      - venue_locked
      - venue_unavailable
      - lead_linked_elsewhere
      - same_lead
      - not_found
      - lead_archived
      - both_converted
      - target_archived
      - target_rejected
      - target_event_closed
      - other_venue_event
      - access_denied
      - event_not_found
      - event_closed
      - lead_moved_concurrently
      - validation_requires_event
      - lead_deleted
    WebhookEventType:
      type: string
      enum:
      - lead.created
      - lead.archived
      - lead.merged
      - event.created
      - event.status_changed
      - event.stage_changed
      - quote.created
      - quote.status_changed
      - invoice.issued
      - invoice.paid
      - event.email_received
      - task.created
      - task.completed
      - person.created
      - company.created
    QuoteErrorReason:
      type: string
      description: '409 state refusals, 400 validation (`min_price` with `details.params`; `package_article`: the line is an article of a package, write the package line; `package_discount_amount`: a package takes a percent discount only), 402 plan.'
      enum:
      - platform_quote_read_only
      - platform_quote_delete_forbidden
      - platform_version_signed
      - quote_conflict
      - quote_changed
      - quote_locked
      - quote_signed
      - quote_cancelled
      - quote_not_cancellable
      - quote_has_active_invoice
      - quote_has_amendments
      - quote_superseded
      - amendment_in_flight
      - amendment_nested
      - parent_not_active
      - parent_not_signed
      - parent_fully_invoiced
      - invalid_status
      - not_a_platform_version
      - event_closed
      - event_archived
      - platform_quote_no_document
      - min_price
      - invalid_location_item
      - package_article
      - package_discount_amount
      - no_fields
      - db_rule
      - validation
      - quotes_plan_required
    SignedQuoteImportErrorReason:
      type: string
      description: POST /events/{id}/quotes/import.
      enum:
      - quotes_plan_required
      - event_not_found
      - quote_not_found
      - event_archived
      - quote_not_signable
      - duplicate_reference
      - invalid_pdf
      - invalid_amounts
      - pdf_too_large
      - forbidden
    PlatformErrorReason:
      type: string
      description: Authentication and rate limits (403, 429).
      enum:
      - plan_not_eligible
      - per-ip
      - per-account-minute
      - per-account-day
      - email_rate_limited
    TaskErrorReason:
      type: string
      enum:
      - task_not_found
      - event_not_found
      - assignee_not_found
      - event_archived
      - no_fields
    ErrorReason:
      description: '`details.reason` of an error: snake_case lower case, the same value as the `code` of the matching MCP tool error. One list per domain.'
      anyOf:
      - $ref: '#/components/schemas/PlatformErrorReason'
      - $ref: '#/components/schemas/EventErrorReason'
      - $ref: '#/components/schemas/LeadErrorReason'
      - $ref: '#/components/schemas/TaskErrorReason'
      - $ref: '#/components/schemas/QuoteErrorReason'
      - $ref: '#/components/schemas/CatalogErrorReason'
      - $ref: '#/components/schemas/SignedQuoteImportErrorReason'
      - $ref: '#/components/schemas/EmailErrorReason'
    WebhookSubscription:
      type: object
      description: An outbound webhook subscription (Zapier or custom endpoint).
      properties:
        id:
          type: string
          format: uuid
        target_url:
          type: string
          description: The endpoint; only its origin (`https://host/…`) without `integrations.manage`.
          example: https://hooks.example.com/joinways
        event_types:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventType'
        source:
          type: string
          enum:
          - zapier
          - custom
        disabled_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Set after 10 failed deliveries in a row.
        disabled_reason:
          type:
          - string
          - 'null'
        last_delivery_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
    EventErrorReason:
      type: string
      description: Events, their sub-resources and the BEO.
      enum:
      - event_not_found
      - event_archived
      - event_not_archived
      - event_has_dependencies
      - venue_locked
      - venue_required
      - venue_unavailable
      - invalid_venue_spaces
      - invalid_dates
      - invalid_timezone
      - invalid_reference
      - invalid_assignee
      - invalid_stage
      - platform_duplicate
      - no_fields
      - revenue_access_required
      - version_conflict
    CatalogErrorReason:
      type: string
      description: 'Catalog writes, packages mostly. All `400` except `package_component` (`409`). `package_price_read_only`: the price and tax rate of a package come from its components, they are never sent (nor `pricing_mode` without `components`). `package_components_required`: a package needs at least one component (or `is_package: false`). `package_flag_required`: `components` sent for a plain item without `is_package: true`. `package_component_duplicate`: an item listed twice. `package_component_self`: the package among its own components. `package_component_not_found`: a component that is not an item of the package''s venue (unknown, another venue, another workspace). `package_component_is_package`: a package cannot contain a package. `package_component_vat_required`: a component has no tax rate and the venue no country to take one from. `package_price_zero`: the components add up to 0. `min_price_above_price`: `min_price` above the price of the package. `price_required`: a plain item (created, or a package turned back into one) without a price. `package_components_refused`: the database refused the composition (a rule above, lost to a concurrent change). `package_component` (409): the item is a component of a package; it cannot be deleted, nor become a package, before it is removed from that package.'
      enum:
      - package_price_read_only
      - package_components_required
      - package_flag_required
      - package_component_duplicate
      - package_component_self
      - package_component_not_found
      - package_component_is_package
      - package_component_vat_required
      - package_price_zero
      - min_price_above_price
      - price_required
      - package_components_refused
      - package_component
    Error:
      type: object
      description: Standard error envelope returned on any non-2xx response.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code (see the Errors table).
              enum:
              - invalid_request
              - unauthorized
              - payment_required
              - forbidden
              - not_found
              - conflict
              - idempotency_conflict
              - payload_too_large
              - idempotency_key_reuse
              - quota_exceeded
              - rate_limited
              - server_error
              example: not_found
            message:
              type: string
              description: Human-readable message (do not parse it). Generic on 5xx.
              example: Event not found
            details:
              description: 'Structured details: field errors on validation (`formErrors`, `fieldErrors`), the query parameter at fault (`field`), `reason` (a stable code) on refusals, or `null`.'
              oneOf:
              - type: object
                additionalProperties: true
                properties:
                  reason:
                    $ref: '#/components/schemas/ErrorReason'
                  field:
                    type: string
                    description: The parameter or body field at fault.
              - type: 'null'
    EmailErrorReason:
      type: string
      description: POST /events/{id}/emails.
      enum:
      - event_not_found
      - event_archived
      - connection_not_found
      - connection_inactive
      - connection_cannot_send
      - no_connection
      - reconnect_required
      - email_rate_limited
  responses:
    Unauthorized:
      description: Missing, invalid, expired or revoked bearer token (`unauthorized`).
      headers:
        WWW-Authenticate:
          description: RFC 6750 challenge pointing at the protected resource metadata (RFC 9728).
          schema:
            type: string
          example: Bearer resource_metadata="https://joinways.app/.well-known/oauth-protected-resource/api/v1", scope="mcp.read mcp.write"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Invalid or expired token
              details: null
    NotFound:
      description: Not found in this workspace, or the id of the path is not a UUID (`not_found`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: Event not found
              details: null
    Forbidden:
      description: '`forbidden`: the token lacks the scope, its owner''s role lacks the permission named by the operation, or the workspace has neither the Pro plan nor a trial (`details.reason` `plan_not_eligible`).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: forbidden
              message: 'Missing required permission: quotes.manage'
              details: null
    RateLimited:
      description: 'Too many requests (`rate_limited`). `details.reason`: `per-ip`, `per-account-minute`, `per-account-day`, or `email_rate_limited` (email budget). Always carries `Retry-After`: wait that many seconds.'
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Too many requests
              details:
                reason: per-account-minute
    BadRequest:
      description: Validation failed (`invalid_request`). For a body that fails the schema, `details` holds `formErrors` and `fieldErrors`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_request
              message: Validation failed
              details:
                formErrors: []
                fieldErrors:
                  start_date:
                  - Required
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: 'Optional client-generated key (1 to 255 characters, e.g. a UUID v4) that makes the request idempotent for 24 hours: a retry with the same key replays the recorded response (marked `Idempotency-Replayed: true`) instead of executing the operation again. Same key with another body: `422 idempotency_key_reuse`; while the first request runs: `409 idempotency_conflict`. See the **Idempotency** section.

        '
      schema:
        type: string
        minLength: 1
        maxLength: 255
      example: 5b0c6f1e-2f4a-4c1e-9d3b-7a2e8f0c1d23
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or OAuth token
      description: 'Paste a token in the `Authorization: Bearer …` header: an **API key** (`jw_…`, created in Settings → Developers → API keys, acting with the role of the member who created it) or an **OAuth 2.1 access token** (`jw_oat_…`). A token is bound to a single workspace.

        '
    oauth2:
      type: oauth2
      description: 'OAuth 2.1 authorization code grant with mandatory PKCE (S256). Access tokens are opaque strings prefixed `jw_oat_`, presented as `Authorization: Bearer …`: valid 1 hour with a refresh token (`jw_ort_…`, rotated on each use, 90 days idle), 30 days for a client without the refresh grant. Send `resource=https://joinways.app/api/v1` (RFC 8707). Clients register dynamically or use an https `client_id` (Client ID Metadata Document). Tokens are bound to a single workspace.

        '
      flows:
        authorizationCode:
          authorizationUrl: https://joinways.app/oauth/authorize
          tokenUrl: https://joinways.app/api/oauth/token
          refreshUrl: https://joinways.app/api/oauth/token
          scopes:
            mcp.read: Read the workspace data the member's role can read.
            mcp.write: Create, update, delete and actions within the member's role (implies read).