Vault Pipeline

After all signers complete an envelope, the envelope moves to completed — it is not vaulted automatically. Vaulting is a deliberate action: an organization admin or custodian explicitly vaults the completed document, which creates the UCC §9-105 authoritative copy and establishes control. This runs the multi-step vault pipeline below. Paper uploads follow a similar path, vaulted explicitly from the uploaded file.

Vaulting is a manual step

A completed envelope stays completed until someone with vault access vaults it. Trigger the pipeline with POST /api/v2/partner/envelopes/:id/vault-in-signed (e-sign) or POST /api/v2/partner/envelopes/:id/vault-in-upload (paper). Sales users cannot vault. Do not poll for vaulted after completed expecting it to happen on its own.

Pipeline flow

Admin / custodian triggers vault-in        Loyva Vault Pipeline
(POST .../vault-in-signed) ──────────────>     │
                                                ▼
                                  1. Load envelope (skip if already vaulted)
                                  2. Fetch signed PDF from signing provider
                                  3. Upload authoritative (watermarked) copy
                                     → authoritative vault (single-copy enforced)
                                  4. Upload non-authoritative copy
                                     → backup bucket
                                  5. Fetch + upload signing-provider audit PDF
                                     (non-fatal if missing)
                                  6. Build + upload Loyva vault custody record PDF
                                     (submission ref, document titles, hash,
                                      actor identity)
                                  7. Update envelope with vault paths,
                                     document hash, metadata
                                  8. Preliminary compliance eval (checks 1–6)
                                  9. Generate + upload UCC §9-105 certificate JSON
                                 10. Transition envelope status to `vaulted`
                                 11. Final compliance eval (all 8 checks) +
                                     re-upload certificate with final result
                                 12. Append audit + event log rows
                                 12b. Auto-assign the vaulting admin/custodian as
                                      initial custodian (Check 3)
                                 13. Dispatch outbound webhook events:
                                     vault.stored + vault.compliance.passed
                                     or vault.compliance.failed

Artifacts written per envelope

Artifact	Notes
Authoritative signed PDF (watermarked)	Single-copy enforced; SHA-256 is the envelope's document_hash
Non-authoritative copy	Flagged non_authoritative in object metadata
Signing-provider submission audit PDF	Optional; skipped if the provider returns none
Loyva vault custody record PDF	Generated by Loyva; human-readable chain-of-custody
UCC §9-105 certificate JSON	All 8 check results + legal notices

Timeline

Once vault-in is triggered, the pipeline typically completes in 5–30 seconds.

Step	Typical duration
Vault-in request received	< 1s
PDF fetch + authoritative upload + hash	2–5s
Custody record + audit PDF upload	1–3s
Compliance evaluation (×2)	< 1s
Certificate generation + re-upload	< 1s
Webhook dispatch	< 1s
Total	5–15s (typical)

Weekly integrity re-verification

A scheduled job runs every Sunday at 04:00 UTC and re-verifies a rolling batch of vaulted envelopes. For each envelope the pipeline:

1. Downloads the authoritative bytes
2. Recomputes the SHA-256 and compares it to the stored document_hash
3. Records the result (pass or mismatch) in the envelope's integrity history
4. Flags mismatches for Loyva's platform team to investigate

Integrity failures are surfaced to partners through webhook events (see below).

Webhook events fired

After the pipeline completes, these events are sent to every active partner webhook URL registered on the org:

1. vault.stored — PDF stored in vault with hash and path
2. vault.compliance.passed — All 8 checks satisfied (score = 100)
3. vault.compliance.failed — One or more checks failed; payload includes missing_requirements

Monitoring

Poll the envelope status:

curl https://api.stg.loyva.net/api/v2/partner/envelopes/env_abc/status \
  -H "X-API-Key: lk_your_key"

Statuses:

• completed — All signatures in; ready to vault (awaiting an admin/custodian vault-in — does not advance on its own)
• vaulted — Pipeline complete, document secured, certificate generated

After triggering vault-in, prefer the vault.stored / vault.compliance.* webhooks over polling.

Error handling

If the pipeline fails at any step:

• The envelope remains in completed status (not vaulted)
• The vault-in request returns an error; simply trigger vault-in again once the underlying issue is resolved (the pipeline is idempotent and skips an already-vaulted envelope)
• Re-run the live compliance evaluator via GET /api/v2/partner/envelopes/:id/compliance once the underlying issue is fixed. This recomputes the score against the current envelope state — it does not re-run the vault pipeline or regenerate the certificate PDF.
• If a download-time hash mismatch is detected, a vault.document.tamper_detected event is surfaced internally so Loyva can investigate (the outbound webhook event type is reserved).