craaft Webhooks API

openapi: 3.2.0
info:
  title: Craaft Webhooks API
  version: 1.0.0
  description: 'Personal-access-token API for Craaft. See `docs/api.md` for the

    narrative guide, rate limits, and worked examples.'
  contact:
    name: Craaft
servers:
- url: https://craaft.io/api/v1
  description: Production
- url: http://localhost:8080/api/v1
  description: Local
security:
- bearerAuth: []
tags:
- name: Webhooks
paths:
  /webhooks/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Subscription id (from GET /projects/{projectId}/webhooks)
    patch:
      summary: Update a webhook subscription
      description: 'Board admins on Pro boards only (authz via subscription lookup).

        Partial update - send only the fields to change. A downgraded (Free)

        board gets 402 here; DELETE stays open so it can still clean up.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                description:
                  type: string
                format:
                  type: string
                  enum:
                  - craaft
                  - slack
                  - discord
                events:
                  type: array
                  items:
                    type: string
                active:
                  type: boolean
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '400':
          description: Malformed body or invalid format/events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Free plan - integrations need Pro
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Not a board admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Webhooks
      operationId: patchWebhooksById
      x-operation-id-source: derived
    delete:
      summary: Delete a webhook subscription
      description: Board admin only. Not plan-gated so downgraded boards can clean up.
      responses:
        '204':
          description: Deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Not a board admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Webhooks
      operationId: deleteWebhooksById
      x-operation-id-source: derived
components:
  schemas:
    WebhookSubscription:
      type: object
      required:
      - id
      - endpointId
      - url
      - description
      - format
      - events
      - active
      - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Subscription id (the handle for update/delete)
        endpointId:
          type: string
          format: uuid
          description: Endpoint id at the workspace level
        url:
          type: string
          format: uri
          description: The target URL for deliveries
        secret:
          type: string
          description: HMAC signing secret for 'craaft' deliveries (X-Craaft-Signature). Returned only when the webhook is created, so copy it then; to get a new one, delete the webhook and add it again. Slack/Discord deliveries are unsigned and ignore it.
        description:
          type: string
          description: Optional label
        format:
          type: string
          enum:
          - craaft
          - slack
          - discord
          description: Delivery format (craaft=signed JSON envelope; slack/discord=message POST)
        events:
          type: array
          items:
            type: string
          description: Event filter (empty=all events; non-empty=only listed events)
        active:
          type: boolean
        createdAt:
          type: string
          format: date-time
        recentDeliveries:
          type: array
          description: Last few delivery attempts (most recent first), capped at 10
          items:
            $ref: '#/components/schemas/WebhookDelivery'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    WebhookDelivery:
      type: object
      required:
      - event
      - status
      - statusCode
      - attempts
      - error
      - createdAt
      properties:
        event:
          type: string
          description: The broadcast event name (e.g. 'card.created')
        status:
          type: string
          enum:
          - delivered
          - failed
          description: Delivery outcome
        statusCode:
          type: integer
          description: HTTP status code from the webhook URL
        attempts:
          type: integer
          description: Number of delivery attempts
        error:
          type: string
          description: Error message when status is failed; empty string on success (never null)
        createdAt:
          type: string
          format: date-time
  responses:
    NotFound:
      description: Resource doesn't exist or caller isn't a member of its workspace
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    sessionAuth:
      type: apiKey
      in: cookie
      name: craaft_session
      description: 'Browser session cookie (`__Host-craaft_session` in production,

        `craaft_session` in dev), set at sign-in. Not obtainable through

        this API - it''s here only so the handful of session-only routes

        below (the OAuth consent screen''s own endpoints, connected-apps

        management) can be marked accurately. They reject both bearer

        schemes with a 403.

        '
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: cra_<24 base64url chars>
      description: 'Two token schemes, same permissions. `cra_<24 base64url chars>` is a

        personal access token minted in Settings, doesn''t expire on its own,

        and is revoked from the same page. `cro_<32 base64url chars>` is an

        OAuth access token issued to an OAuth client (an MCP client such as

        Claude) via the authorization-code-with-PKCE flow; it expires after

        1 hour and the client refreshes it. Either token authenticates as

        the user who authorized it, with that user''s exact permissions.


        A token can be read-only: a personal access token created with

        access `read`, or an OAuth grant with scope `craaft:read`. A

        read-only token can send GET, HEAD and OPTIONS; any other method

        gets `403` with "this token is read-only; this request needs a

        token with read and write access", before the request is handled.


        A token can also be limited to chosen boards. Other boards then

        behave as if they don''t exist (`404`, or left out of lists), and

        `POST /projects`, `/imports`, `/members` and `/invitations` answer

        `403` with "this token is limited to some boards; this request

        needs a token for all boards".


        OAuth clients discover every endpoint they need - authorization,

        token, dynamic client registration, revocation - at

        `/.well-known/oauth-authorization-server` (RFC 8414); they don''t

        need to be told the URLs out of band.

        '