---
title: "Signing event"
method: POST
path: "signingEvent"
---

# Signing event

`POST signingEvent` (webhook)

Sent to `webhookUrl` as a signing progresses. Deliveries carry
`X-Tvarka-Signature: sha256=<HMAC-SHA256 of the raw body>` keyed with
your webhook secret - verify it before acting - plus
`X-Tvarka-Idempotency-Key` and `X-Tvarka-Event`.

Prefer `X-Tvarka-Signature-V2: t=<unix seconds>,v1=<hex>`, where
`v1` is the HMAC-SHA256 of `t + "." + raw body` under the same secret
and `t` equals `X-Tvarka-Timestamp`. Reject deliveries whose `t` is
more than 5 minutes from your clock: a replayed delivery fails.

Retried with backoff on 5xx and transport failures. Delivery is a
convenience, never the only way to learn an outcome: polling always
works, and a failed delivery never changes a signing's state.

The payload never carries a signer's identity data - no personal
code, no certificate subject, no phone number. It echoes the email
you supplied and nothing more.

## Payload

- object
  - `event` 'signing.signer_signed' | 'signing.signer_declined' | 'signing.signer_failed' | 'signing.completed' | 'signing.declined' | 'signing.cancelled' | 'signing.expired' | 'signing.failed'
  - `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.
  - `externalId` string
  - `occurredAt` string, date-time
  - `completionMode` 'qes_ceremony' | 'esign_ceremony' | 'sandbox_simulation'
  - `level` 'esign': Present on a simple e-signature.
  - `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.

## 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)