Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. By signing up you are subscribing to the APIs.io and API Evangelist
newsletters — you can unsubscribe from any issue. See our
Privacy Policy and Terms.
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.