---
title: "Headless signature event"
method: POST
path: "signatureEvent"
---

# Headless signature event

`POST signatureEvent` (webhook)

Same delivery, headers, HMAC signatures and 72-hour retry as
`signingEvent`. `signature.confirmation_required` carries the new
`verificationCode` when the second confirmation starts. Never
personal data: no personal code, no phone, no certificate subject.

## Payload

- object
  - `event` 'signature.confirmation_required' | 'signature.signed' | 'signature.declined' | 'signature.expired' | 'signature.failed' | 'signature.cancelled', required
  - `signatureId` string, uuid, required
  - `status` 'pending' | 'signed' | 'declined' | 'expired' | 'failed' | 'cancelled', required
  - `occurredAt` string, date-time, required
  - `externalId` string
  - `step` 'authentication' | 'signing'
  - `verificationCode` string
  - `nextAction` NextAction: What to show the signer now (v1.11.0). `revision` grows with every step and once more at the end; ignore a webhook whose revision is older than the one you hold, and poll when unsure.
    - `type` 'compare_code' | 'confirm_certificate' | 'scan_qr' | 'open_app' | 'wait' | 'none', required
    - `revision` integer, required
    - `verificationCode` string: With `compare_code`.
    - `qrLink` string, uri: With `scan_qr`. Show as a QR code; it changes every second.
    - `refreshAfterSeconds` integer: With `scan_qr`: fetch a new link after this long.
    - `appLink` string, uri: With `open_app`: open on the signer's phone.
    - `expiresAt` string, date-time
  - `failureReason` 'identity_mismatch' | 'certificate_not_qualified' | 'certificate_rotated' | 'provider_error' | 'timestamp_unavailable' | 'initiation_unknown': `identity_mismatch` - the certificate belongs to another person. `certificate_not_qualified` - the certificate cannot sign documents. `certificate_rotated` - the signer's certificate changed since Tvarka last saw it; the new one is kept, so a retry needs one confirmation. `provider_error` - the signing service failed. `timestamp_unavailable` - no qualified timestamp could be obtained. `initiation_unknown` - the start may have reached the signer's phone but no answer came back; it is never repeated. Ask the signer to dismiss any prompt and retry after two minutes. None of these is billed.
  - `completionMode` 'signed' | 'sandbox_simulation'
  - `sandbox` boolean
  - `document` object
    - `sha256` string

## Acknowledgement `200`

Acknowledged. Any 2xx stops redelivery.

## Other responses

- `401`: An RFC 9457 problem document.
- `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)