openapi: 3.1.0
# Published on the public docs site, as a reference page and as this file.
# A contract without this key is internal.
x-docs-visibility: public
info:
  title: Assessor.io API v2 (public) - Webhook Subscriptions
  version: 1.0.1
  description: |
    Manage the account's outbound webhook subscriptions. All four operations
    take the single scope webhooks:manage.

    The signing secret is write-only: it is accepted on create and never
    returned by any read. If it is lost, delete the subscription and register a
    new one.

    Delivery behaviour, for the receiver you register:
    Assessor.io POSTs application/json with a body carrying three properties -
    event, accountId, and payload - plus an X-Assessor-Event header carrying the
    event type, and - when the subscription has a secret - an
    X-Assessor-Signature header holding 'sha256=' followed by the hex
    HMAC-SHA256 of the exact raw body. Verify against the raw bytes, not a
    re-serialised object. Any
    2xx counts as accepted; anything else is retried, up to 3 attempts in all,
    waiting at least 1 minute and then 2 minutes between them, after which the
    subscription's deliveryFailureCount is incremented. Deliveries are queued, then drained by a scheduled processor,
    so they are near-real-time rather than synchronous.

    Event names come from a CLOSED server-side catalogue (WEBHOOK_EVENT_TYPES;
    the "Event types" table in the v2 integration guide is the whole of it).
    A name outside it is refused with a 400 that names it; it used to be
    accepted and then silently never fire.

    Three of the catalogue's names are delivered AFTER their database
    transaction commits, because the rows behind them are written beside an
    audit record: registration.accepted, communication.created and
    communication.dispatch.queued. On the wire they are identical to
    every other event. The one consequence: if the delivery queue cannot be
    reached at that moment the write still stands and nothing is queued for it,
    so treat those three as at-most-once and reconcile against the resource if
    you need certainty.
servers:
  - url: /
security:
  - serviceToken: []
tags:
  - name: PublicWebhooks
paths:
  /api/v2/public/accounts/{accountId}/webhooks:
    get:
      tags: [PublicWebhooks]
      operationId: v2ListWebhookSubscriptions
      summary: List the account's webhook subscriptions.
      description: Not paginated - the full set is returned. Scope webhooks:manage.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
      responses:
        '200':
          description: Subscriptions loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookListResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
    post:
      tags: [PublicWebhooks]
      operationId: v2CreateWebhookSubscription
      summary: Register a webhook subscription.
      description: |
        Creates an active subscription. The response omits the secret even on
        the create call. Scope webhooks:manage.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '201':
          description: Subscription created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDetailResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
  /api/v2/public/accounts/{accountId}/webhooks/{subscriptionId}:
    patch:
      tags: [PublicWebhooks]
      operationId: v2SetWebhookSubscriptionActive
      summary: Activate or deactivate a subscription.
      description: |
        The only mutable property is isActive - the URL, events, and secret
        cannot be edited in place. A deactivated subscription stops receiving
        fan-out, and any already-queued delivery for it fails on the next
        processor pass. Scope webhooks:manage.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - $ref: '../components/v2-common.yaml#/components/parameters/SubscriptionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetWebhookActiveRequest'
      responses:
        '200':
          description: Subscription updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDetailResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '404': { $ref: '../../v1/components/errors.yaml#/components/responses/NotFound' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
    delete:
      tags: [PublicWebhooks]
      operationId: v2DeleteWebhookSubscription
      summary: Unsubscribe.
      description: Permanently removes the subscription. Scope webhooks:manage.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - $ref: '../components/v2-common.yaml#/components/parameters/SubscriptionId'
      responses:
        '200':
          description: Subscription deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeletedResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '404': { $ref: '../../v1/components/errors.yaml#/components/responses/NotFound' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
components:
  securitySchemes:
    serviceToken:
      $ref: '../components/v2-security.yaml#/components/securitySchemes/serviceToken'
  schemas:
    PublicWebhook:
      type: object
      description: |
        Whitelisted subscription projection (toPublicWebhook). accountId,
        updatedAt, and above all secret are excluded.
      required: [id, url, events, isActive, deliveryFailureCount]
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
        isActive:
          type: boolean
        lastDeliveryAt:
          type: integer
          description: Epoch milliseconds of the last successful delivery. Absent until one succeeds.
        deliveryFailureCount:
          type: integer
          description: Cumulative count of deliveries that exhausted all retry attempts.
        createdAt:
          type: integer
          description: Epoch milliseconds.
    CreateWebhookRequest:
      type: object
      description: Validated by normalizeWebhookSubscription. Unknown properties are ignored.
      required: [url, events]
      properties:
        url:
          type: string
          format: uri
          description: Must parse as an http or https URL. Anything else is rejected with 400.
        events:
          type: array
          description: |
            Non-empty array of event-type names from the published catalogue
            (WEBHOOK_EVENT_TYPES). Trimmed and de-duplicated; an array that
            reduces to empty, or one naming an event outside the catalogue, is
            rejected with 400.
          minItems: 1
          items:
            type: string
        secret:
          type: string
          description: |
            Optional HMAC-SHA256 signing secret. Write-only - it is never
            echoed back by this or any other operation. Without it, deliveries
            arrive unsigned.
    SetWebhookActiveRequest:
      type: object
      required: [isActive]
      properties:
        isActive:
          type: boolean
          description: Must be a boolean. A missing or non-boolean value is rejected with 400.
    WebhookListResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/PublicWebhook'
    WebhookDetailResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              $ref: '#/components/schemas/PublicWebhook'
    WebhookDeletedResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              type: object
              required: [id, deleted]
              properties:
                id:
                  type: string
                deleted:
                  type: boolean
