Vault Pipeline

After all signers complete an envelope, Loyva automatically processes the signed document through a multi-step asynchronous vault pipeline. Paper uploads follow a similar path but run synchronously at upload time.

Pipeline flow

Signing provider                Loyva Webhook Gateway            Vault Queue
(submission.completed) ────────> Verify HMAC signature ────────>     │
                                 Update envelope status               ▼
                                                               Loyva Vault Pipeline
                                          │
                                          ▼
                                  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 hash-chained audit + event log rows
                                 12b. Auto-assign envelope creator 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

The entire pipeline typically completes in 5–30 seconds after the last signer completes.

Step	Typical duration
Webhook receipt	< 1s
Queue processing start	1–3s
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, vault pipeline pending
• vaulted — Pipeline complete, document secured, certificate generated

Prefer webhooks over polling for production integrations.

Error handling

If the pipeline fails at any step:

• The envelope remains in completed status (not vaulted)
• The pipeline is retried automatically; unrecoverable failures land in a dead-letter queue for Loyva operators to investigate
• 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).