---
title: "Webhook subscription event"
method: POST
path: "subscriptionEvent"
---

# Webhook subscription event

`POST subscriptionEvent` (webhook)

Sent to each subscription registered with `POST /v1/webhooks` for
the events it chose (v1.12.0). Same headers, HMAC signatures and
72-hour retry as `signingEvent`, under the same webhook secret.
`eventId` equals the `X-Tvarka-Idempotency-Key` header: use it to
process each event once. `signing` is the signing at the moment of
the event, as `GET /v1/signings/{signingId}` shows it, without
ceremony links. Answer `410 Gone` to remove the subscription.

## Payload

- object
  - `event` 'signing.signer_signed' | 'signing.signer_declined' | 'signing.signer_failed' | 'signing.completed' | 'signing.declined' | 'signing.cancelled' | 'signing.expired' | 'signing.failed' | 'form_request.opened' | 'form_request.submitted' | 'form_request.completed' | 'form_request.cancelled' | 'form_request.expired' | 'form_request.failed', required
  - `eventId` string, required
  - `webhookId` string, uuid, required
  - `signingId` string, uuid, required
  - `status` 'pending' | 'completed' | 'declined' | 'cancelled' | 'expired' | 'failed', required: `pending` - at least one signer can still sign. `completed` - every signer signed. `declined` - somebody declined and nobody else can still sign. `expired` - the window closed first. `cancelled` - you retracted it. `failed` - the signing could not be prepared.
  - `externalId` string
  - `occurredAt` string, date-time, required
  - `completionMode` 'qes_ceremony' | 'esign_ceremony' | 'sandbox_simulation'
  - `level` 'esign'
  - `signer` object
    - `signerId` string, uuid
    - `email` string, email
    - `status` 'pending' | 'signed' | 'declined' | 'cancelled' | 'expired' | 'failed' | 'simulated' | 'waiting' | 'recorded': `waiting` - a sequential signer whose turn has not come; their ceremony link answers 404 until it does. `failed` - the signer's requested PDF stamp could not be prepared. `recorded` - a viewer. Never invited, never blocks completion.
    - `declineReason` string
  - `document` SignedDocument: The newest signed output. Absent until somebody signs, except on a sandbox simulation, where it describes the unsigned artifact.
    - `sha256` string
    - `bytes` integer
    - `mimeType` string
    - `sandbox` boolean: Present and true only on a sandbox simulation. The bytes are a real file to which no signature was added.
    - `signed` boolean: Present and false only on a sandbox simulation. Absent on a real signing, where the output is signed by definition.
  - `signing` Signing, required
    - `signingId` string, uuid
    - `status` 'pending' | 'completed' | 'declined' | 'cancelled' | 'expired' | 'failed': `pending` - at least one signer can still sign. `completed` - every signer signed. `declined` - somebody declined and nobody else can still sign. `expired` - the window closed first. `cancelled` - you retracted it. `failed` - the signing could not be prepared.
    - `level` 'qualified' | 'esign'
    - `processingStage` 'awaiting_signers' | 'finalizing': While `pending`: `finalizing` once every signer signed and the file is being sealed (a simple e-signature's document timestamp).
    - `title` string
    - `delivery` 'link' | 'email'
    - `signingOrder` 'parallel' | 'sequential': `sequential` releases one signer at a time in the order they were posted. The signers who are waiting hold a ceremony link that answers 404 until their turn, so the ordering is enforced rather than merely unsent. A decline stops the workflow at the decliner's turn: the signing settles `declined` and the signers still waiting are cancelled.
    - `softDeadlineAt` string, date-time, nullable: The date the signing is wanted by, as opposed to `expiresAt`, which is the date it dies on. Nothing expires here; it is when the one automatic reminder goes out.
    - `externalId` string, nullable
    - `templateId` string, uuid: Present when the signing was sent from a template (v1.14.0).
    - `createdAt` string, date-time
    - `expiresAt` string, date-time, nullable
    - `completedAt` string, date-time, nullable
    - `completionMode` 'qes_ceremony' | 'esign_ceremony' | 'sandbox_simulation' | 'null', nullable: `qes_ceremony` means human eID signing. `esign_ceremony` means a completed simple e-signature. `sandbox_simulation` exercises lifecycle/webhook integration and creates no signature; its artifact is flagged `sandbox: true`.
    - `erasedAt` string, date-time, nullable
    - `detail` string: Present when the status needs a sentence of explanation.
    - `signers` Signer[]
      - `signerId` string, uuid
      - `role` 'signer' | 'viewer': A `viewer` is a recorded non-signing party: no invitation is raised, no ceremony link exists, and they never hold up completion. Tvarka sends them nothing - you hold the webhook and the download, and distribute. At least one signer is required.
      - `email` string, email, nullable
      - `name` string, nullable
      - `language` 'lt' | 'en' | 'et' | 'lv' | 'pl' | 'uk' | 'ru' | 'de' | 'fr' | 'es' | 'it' | 'nl' | 'sv' | 'da' | 'nb' | 'fi'
      - `status` 'pending' | 'signed' | 'declined' | 'cancelled' | 'expired' | 'failed' | 'simulated' | 'waiting' | 'recorded': `waiting` - a sequential signer whose turn has not come; their ceremony link answers 404 until it does. `failed` - the signer's requested PDF stamp could not be prepared. `recorded` - a viewer. Never invited, never blocks completion.
      - `ceremonyUrl` string, uri: Present only while this signer can still sign. A finished or retracted invitation has no live URL.
      - `signedAt` string, date-time, nullable
      - `declinedAt` string, date-time, nullable
      - `declineReason` string
      - `methodsAllowed` SigningMethod[]
      - `actualMethod` 'nfc' | 'smart_id' | 'mobile_id': The orchestration methods. For direct LT ATK reader, USB, raw CAdES and lower-level NFC integration, use the ATK API.
      - `identityLocked` boolean
      - `authentication` object: `level: esign` signers: the protection type only, never the code.
        - `type` 'email_link' | 'access_code' | 'sms'
      - `signingPurpose` 'signature' | 'confirmation' | 'visa' | 'registration' | 'null', nullable: Accepted immutable purpose; null for a viewer.
      - `visibleSignature` union: The accepted placement, or null. A signer of a signing sent from a template carries the role's saved box (`TemplateVisibleSignature`, v1.14.1).
        - union: Any workspace may place this signer's visible PDF stamp. Use either page coordinates in PDF points from the lower-left MediaBox corner, or one existing unsigned signature field. The accepted value is immutable and returned on the signer. PDF only; field binding cannot be combined with `document.flatten: true`. `page` is 1-based. Coordinates are finite PDF points (1/72 inch) in unrotated page space; x/y are offsets even when the MediaBox origin is nonzero. The whole box must fit MediaBox and CropBox. Minimum size is 148 x 52 pt; placement requires /UserUnit: 1. A field must have one usable visible widget, be unsigned and unlocked, and meet the same geometry rules. Earlier field locks, ambiguous names and fields already reserved for another signer are rejected. Explicit positions do not become cascade anchors. Do not send this property for viewers. No entitlement is needed (v1.13.1); the company logo and VIP whitelabel are separate. Omit the property to use normal corner placement; configured workspace branding still applies.
          - object
            - `page` integer, required
            - `x` number, required
            - `y` number, required
            - `width` number, required
            - `height` number, required
          - object
            - `field` string, required
        - union: A box saved on a template role, and the box a signer gets from it (v1.14.1). The shape of `VisibleSignature`. The sizes are those of the template's level, the sizes the Tvarka Sign app saves it with: at least the default qualified stamp (103.18 x 35.72 pt) or the default e-signature mark (119.06 x 45.64 pt), and at most three times that. When a qualified template is sent, the box is checked by these sizes and must fit the PDF. A box sent to `POST /v1/templates` is a box sent in a request, so it keeps the `VisibleSignature` rules, 148 x 52 pt at least. A field binding keeps the field rules of `VisibleSignature`.
          - object
            - `page` integer, required
            - `x` number, required
            - `y` number, required
            - `width` number, required
            - `height` number, required
          - object
            - `field` string, required
      - `identityMatched` boolean, nullable: True only after a locked signer completes the real ceremony.
      - `simulatedAt` string, date-time, nullable
      - `emailStatus` 'not_requested' | 'pending' | 'accepted' | 'failed' | 'cancelled' | 'unknown': Initial invitation email state. Accepted means the email backend accepted the message, not inbox delivery. Unknown denotes legacy best-effort delivery whose outcome was not recorded. Sequential signers stay not_requested until their turn is released.
      - `emailAcceptedAt` string, date-time, nullable
    - `document` SignedDocument: The newest signed output. Absent until somebody signs, except on a sandbox simulation, where it describes the unsigned artifact.
      - `sha256` string
      - `bytes` integer
      - `mimeType` string
      - `sandbox` boolean: Present and true only on a sandbox simulation. The bytes are a real file to which no signature was added.
      - `signed` boolean: Present and false only on a sandbox simulation. Absent on a real signing, where the output is signed by definition.
    - `evidence` object: A completed simple e-signature (`level: esign`).
      - `available` boolean: False once erased.
      - `referenceCode` string
      - `verificationUrl` string, uri
      - `separateSummary` boolean
      - `sealedAt` string, date-time, nullable
      - `sandbox` boolean
      - `validation` object
        - `status` 'notApplicable'

## Acknowledgement `200`

Acknowledged. Any 2xx stops redelivery.

## Other responses

- `401`: An RFC 9457 problem document.
- `410`: Gone. Tvarka removes the subscription.
- `429`: An RFC 9457 problem document.

---

[API](https://skmtc.dev/tvarka/apis/tvarka-sign-api.md) · [All operations](https://skmtc.dev/tvarka/apis/tvarka-sign-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tvarka/apis/tvarka-sign-api/revisions/e3fdd995c013?raw)