Coldrig Webhooks API

openapi: 3.2.0
info:
  title: Coldrig Dev Webhooks API
  version: 0.3.0
  contact:
    name: EpiphanyMade
    email: support@coldrig.dev
  license:
    name: MIT
  description: 'Operations tagged webhooks across 2 of this provider''s published API definitions: coldrig-dev-openapi.yaml, coldrig-dev-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.coldrig.dev
  description: Production API host.
security:
- bearerAuth: []
tags:
- name: Webhooks
paths:
  /webhook-subscriptions:
    get:
      operationId: get_webhooks
      tags:
      - Webhooks
      summary: List every outbound webhook subscription for the account
      description: Secrets are never returned on reads — they are shown once at create/rotate. Use GET /webhook-subscriptions/{id} for one subscription plus its recent delivery and attempt log.
      responses:
        '200':
          description: Webhook subscription summaries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: configure_webhook_create
      tags:
      - Webhooks
      summary: Create an outbound webhook subscription
      description: 'Push reply, bounce, soft_bounce, complaint, and unsubscribe events to your own HTTPS endpoint instead of polling GET /activity. Deliveries are signed `X-Coldrig-Signature: sha256=HMAC-SHA256(secret, raw body)`. URLs must be https and resolve to a public host — private/link- local/metadata IPs are rejected, re-validated on every delivery.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateInput'
      responses:
        '201':
          description: Subscription created — the response carries the signing secret once.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCreateResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
  /webhook-subscriptions/{id}:
    parameters:
    - $ref: '#/components/parameters/WebhookSubscriptionId'
    get:
      operationId: get_webhook
      tags:
      - Webhooks
      summary: One webhook subscription plus its recent delivery and attempt log
      responses:
        '200':
          description: Subscription detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: configure_webhook_update
      tags:
      - Webhooks
      summary: Update a webhook subscription — url, event filter, active flag, or rotate the…
      description: At least one of url, eventTypes, secret, or active must be present. active:true re-enables a subscription the delivery pump auto-disabled after 5 consecutive terminal failures; active:false pauses delivery without deleting. Rotating the secret returns it once in the response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookUpdateInput'
      responses:
        '200':
          description: Subscription updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookUpdateResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: configure_webhook_delete
      tags:
      - Webhooks
      summary: Delete a webhook subscription
      responses:
        '200':
          description: Deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://api.coldrig.dev
      description: Production API host.
components:
  schemas:
    WebhookCreateResponse:
      allOf:
      - $ref: '#/components/schemas/WebhookSummary'
      - type: object
        required:
        - secret
        properties:
          secret:
            type: string
            description: HMAC signing secret — shown once on create, never returned on reads.
    WebhookAttemptView:
      type: object
      required:
      - deliveryId
      - attemptNo
      - ok
      - statusCode
      - error
      - ts
      properties:
        deliveryId:
          type: string
        attemptNo:
          type: integer
        ok:
          type: boolean
        statusCode:
          type:
          - integer
          - 'null'
        error:
          type:
          - string
          - 'null'
        ts:
          type: integer
    WebhookDeliveryView:
      type: object
      required:
      - id
      - eventId
      - eventType
      - status
      - attempts
      - lastStatusCode
      - lastError
      - nextAttemptAt
      - createdAt
      - lastAttemptAt
      - deliveredAt
      properties:
        id:
          type: string
        eventId:
          type: string
        eventType:
          type: string
        status:
          type: string
        attempts:
          type: integer
        lastStatusCode:
          type:
          - integer
          - 'null'
        lastError:
          type:
          - string
          - 'null'
        nextAttemptAt:
          type: integer
        createdAt:
          type: integer
        lastAttemptAt:
          type:
          - integer
          - 'null'
        deliveredAt:
          type:
          - integer
          - 'null'
    WebhookSummary:
      type: object
      required:
      - id
      - url
      - eventTypes
      - active
      - status
      - disabledReason
      - consecutiveFailures
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
        url:
          type: string
        eventTypes:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventType'
        active:
          type: boolean
        status:
          type: string
          enum:
          - active
          - disabled
        disabledReason:
          type:
          - string
          - 'null'
        consecutiveFailures:
          type: integer
        createdAt:
          type: integer
        updatedAt:
          type: integer
    WebhookCreateInput:
      type: object
      required:
      - url
      - eventTypes
      properties:
        url:
          type: string
          minLength: 1
          maxLength: 2048
          description: 'HTTPS endpoint that receives event POSTs. Must be https and resolve to a public host — private/link-local/metadata IPs are rejected.

            '
        eventTypes:
          type: array
          minItems: 1
          maxItems: 4
          items:
            $ref: '#/components/schemas/WebhookEventType'
          description: Which event types to receive. At least one.
        secret:
          type: string
          minLength: 16
          maxLength: 200
          description: 'Optional HMAC signing secret (>=16 chars). Omit to have the server generate one, returned once on create.

            '
        active:
          type: boolean
          default: true
          description: Whether the subscription delivers immediately. Defaults to true.
    WebhookDetail:
      type: object
      required:
      - subscription
      - recentDeliveries
      - recentAttempts
      properties:
        subscription:
          $ref: '#/components/schemas/WebhookSummary'
        recentDeliveries:
          type: array
          items:
            $ref: '#/components/schemas/WebhookDeliveryView'
        recentAttempts:
          type: array
          items:
            $ref: '#/components/schemas/WebhookAttemptView'
    WebhookUpdateInput:
      type: object
      description: Every field optional; at least one of url, eventTypes, secret, or active must be present.
      properties:
        url:
          type: string
          minLength: 1
          maxLength: 2048
        eventTypes:
          type: array
          minItems: 1
          maxItems: 4
          items:
            $ref: '#/components/schemas/WebhookEventType'
        secret:
          type: string
          minLength: 16
          maxLength: 200
          description: Rotates the signing secret; the new value is returned once in the response.
        active:
          type: boolean
          description: 'Set false to pause delivery without deleting; set true to resume (also re-enables an auto-disabled subscription).

            '
    WebhookEventType:
      type: string
      enum:
      - reply
      - bounce
      - soft_bounce
      - complaint
      - unsubscribe
      description: reply = genuine reply; bounce = HARD (permanent) bounce; soft_bounce = transient bounce; complaint = spam complaint; unsubscribe = typed unsubscribe-link click.
    WebhookUpdateResponse:
      allOf:
      - $ref: '#/components/schemas/WebhookSummary'
      - type: object
        properties:
          secret:
            type: string
            description: Present only when this update rotated the secret; shown once.
  responses:
    NotFound:
      description: Resource not found, or not owned by the authenticated account.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    ValidationError:
      description: Request body failed schema validation.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    Unauthorized:
      description: Missing, invalid, or inactive bearer token.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
  parameters:
    WebhookSubscriptionId:
      name: id
      in: path
      required: true
      description: 'The MCP tools `get_webhooks` and `configure_webhook` take this same identifier as an `id` argument (there is no URL path in MCP tool calls).

        '
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Token returned by POST /signup. One token = one separate account. An app connected with "Sign in with Coldrig" (OAuth) holds its own short-lived token for the same account: it is accepted on the hosted MCP endpoint (/mcp) only, and on no REST route.

        '
    dashboardSessionCookie:
      type: apiKey
      in: cookie
      name: cs_dashboard_session
      description: 'httpOnly session cookie minted by POST /dashboard/session (30-day TTL). Alternative to bearerAuth for /dashboard/* routes only, used by the optional human dashboard SPA. A cookie-authed mutating request (any method other than GET/HEAD) must also send the `X-Coldstart-Client: dashboard` header (global CSRF guard) — bearer-authed requests are exempt.

        '
x-refined-from:
- coldrig-dev-openapi.yaml
- coldrig-dev-openapi.yml