tessio-eu Webhooks API

openapi: 3.2.0
info:
  title: Tessio.Cloud Webhooks API
  version: 0.1.0
  license:
    name: Proprietary
  description: 'The Tessio.Cloud integration API: start an age check, read its result, manage the webhook and read your stats. Every operation takes an API key (`tk_…`) as a Bearer token. This is the public part of the full description, generated from it; the guides are at https://tessio.eu/docs/.'
servers:
- url: https://api.tessio.eu
security:
- bearerAuth: []
tags:
- name: Webhooks
paths:
  /v1/webhook:
    put:
      tags:
      - Webhooks
      summary: Set the project's webhook endpoint
      description: 'Registers (or replaces) the endpoint + the events it should receive (omit `events` to subscribe to all). The first call for a project returns a signing **secret** (shown once); a later call that changes the URL or the event list returns `secret: null` and leaves the existing secret in place, so your signature check keeps working across an edit. Replace it deliberately with `POST /v1/webhook/secret`. Each delivery is POSTed with an `X-Tessio-Event` header and an `X-Tessio-Signature: t=,v1=` header so you can verify it. Deliveries retry with backoff; `GET /v1/age-checks/{id}` stays the reliable fallback.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetWebhookRequest'
      responses:
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '200':
          description: Endpoint set (secret returned once, only when created)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCreated'
        '400':
          description: 'invalid_url (not an absolute http(s) URL) or insecure_url. The endpoint must be https: a delivery is signed, but the signature proves integrity and not confidentiality, so the check outcome would otherwise travel in clear. The hosted service accepts https only.'
        '401':
          description: Missing / invalid / revoked key
      operationId: putV1Webhook
      x-operation-id-source: derived
    get:
      tags:
      - Webhooks
      summary: Get the configured endpoint (never the secret)
      security:
      - bearerAuth: []
      responses:
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookConfig'
        '401':
          description: Missing / invalid / revoked key
        '404':
          description: No endpoint configured
      operationId: getV1Webhook
      x-operation-id-source: derived
    delete:
      tags:
      - Webhooks
      summary: Remove the endpoint (stops deliveries)
      security:
      - bearerAuth: []
      responses:
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '204':
          description: Removed
        '401':
          description: Missing / invalid / revoked key
        '404':
          description: No endpoint configured
      operationId: deleteV1Webhook
      x-operation-id-source: derived
  /v1/webhook/secret:
    post:
      tags:
      - Webhooks
      summary: Replace the signing secret
      description: 'Mints a new signing secret and returns it once. Deliveries are signed when they are sent, so this applies to anything already queued as well as to new events: until you install the new secret, every delivery fails your `X-Tessio-Signature` check. Setting the endpoint does NOT do this, so correcting a URL is safe.'
      security:
      - bearerAuth: []
      responses:
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '200':
          description: Replaced (new secret returned once)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSecret'
        '401':
          description: Missing / invalid / revoked key
        '404':
          description: No endpoint configured
      operationId: postV1WebhookSecret
      x-operation-id-source: derived
components:
  schemas:
    WebhookEventType:
      type: string
      enum:
      - age_check.completed
      - age_check.expired
      - age_check.failed
      - age_check.attempt_failed
      description: '`age_check.completed`: a result is in. `age_check.failed`: a presentation verified but gave no readable answer, because it did not disclose the claim. `age_check.expired`: the request lifetime elapsed with no answer (sandbox checks complete by themselves first). `age_check.attempt_failed`: a presentation failed verification, over either transport, or a wallet sent an error response such as a decline, and the check stays pending, so it is not terminal: the check still ends in one of the other three, announced to an endpoint subscribed to it. It is a notice, not a log: at most one waits unsent per check, one whose check has ended before it is picked up is dropped, and it does not follow the terminal event, except rarely when a delivery is interrupted while being sent. Read the check for `failedAttempts` and `lastFailureCodes`, which count every attempt. An endpoint saved before this event existed stored the events known then, so add it to receive it.

        '
    WebhookCreated:
      type: object
      properties:
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventType'
        secret:
          type:
          - string
          - 'null'
          description: 'Signing secret (whsec_…), shown once, store it to verify X-Tessio-Signature. Present when the call created the endpoint; null when it changed one that already had a secret, because editing the URL or the event list leaves the secret in place so your signature check keeps working. Ask for a replacement with `POST /v1/webhook/secret`.

            '
    Error:
      type: object
      properties:
        error:
          type: string
          description: Machine readable code (for example invalid_from, insufficient_scope, idempotency_key_reuse)
    WebhookSecret:
      type: object
      properties:
        secret:
          type: string
          description: The new signing secret (whsec_…), shown once
    SetWebhookRequest:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          description: 'Absolute https URL to receive events. Any other scheme is refused: http with insecure_url, the rest with invalid_url.'
        events:
          type: array
          description: Event types to receive. Omit (or empty) to subscribe to all.
          items:
            $ref: '#/components/schemas/WebhookEventType'
    WebhookConfig:
      type: object
      properties:
        url:
          type:
          - string
          - 'null'
          format: uri
        events:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventType'
  responses:
    InsufficientScope:
      description: insufficient_scope. The key is valid but may only read stats (`stats:read`), so it cannot call this route. Use a project's key with scope `full`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key (`tk_…`). A project's key with scope `full` calls every `/v1` route for its project; with `stats:read` it calls `/v1/stats/*` only. An organisation's key is always `stats:read` and reads every project in the organisation.