---
name: bijection-zsign
description: "Evaluate and integrate the Zsign component with Bijection."
---

# Zsign

zSign e-signature component for Bijection — send documents, watch signing status reactively, and fetch signed artifacts.

- Package: @bijectionhq/zsign
- Category: Integrations
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/zsign/tree/3c612ca5f759865c954685033a494739c380659e
- Upstream: https://github.com/azlabsio/zsign-plugin/tree/bec1c5281dd36c03041d03920efb4f22cd017d22
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/zsign

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/zsign.git
cd zsign
git checkout 3c612ca5f759865c954685033a494739c380659e
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @zsign/convex. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses zsign. Follow the installation and configuration steps exactly.

# zsign

## Instructions

The zsign component integrates the zSign e-signature API into a Convex backend, handling envelope creation, webhook ingestion, and artifact retrieval. It provides reactive status queries so UI components can subscribe to envelope progress without polling, and runs completion callbacks via internal mutations when documents are signed. Signed PDFs and completion certificates are accessible through component actions once an envelope reaches terminal state.

### Installation

```bash
npm install @zsign/convex
```

Current npm version: `@zsign/convex@0.1.2`

## Use cases

- Adding e-signature flows to a Convex app where you need to track envelope status reactively in the UI without building a separate polling layer
- Running server-side logic (advancing a workflow, updating records) exactly when a document is signed, using at-least-once completion callbacks backed by persistent state
- Implementing idempotent document sends so retries and replays do not create duplicate envelopes or double-charge signing credits
- Ingesting and verifying zSign webhooks with HMAC-SHA256 signature checks, deduplication, and orphaned-event handling before touching your own data
- Retrieving signed PDFs and completion certificates as ArrayBuffers from within Convex actions after an envelope completes

## How it works

Configuration is declared in `convex/convex.config.ts` using `app.use(zsign, { env: { ZSIGN_API_KEY, ... } })`. The component exposes a `Zsign` client class instantiated with `components.zsign`. The `zsign.send(ctx, { file, recipients, operationId, ... })` action uploads a document to the zSign API using a manually built multipart request (required because Convex's runtime FormData drops Blob MIME types) and stores the resulting envelope keyed by `operationId` for idempotent replays.

Webhooks are wired manually in `convex/http.ts` using the exported `verifyWebhookRequest` helper, which validates the `X-Webhook-Signature` HMAC-SHA256 header with 300-second tolerance and supports secret rotation via a previous secret. Verified events are applied with `components.zsign.lib.applyWebhookEvent`. Unknown envelope sessions are stored as orphaned rows and re-attached when the matching envelope arrives. Out-of-order events trigger a reconciliation flow that fetches canonical state from `GET /api/v1/documents/{id}` with a generation guard to prevent stale applies.

Status is exposed through two reactive queries: `zsign.status(ctx, operationId)` returns envelope and recipient detail, and `zsign.list(ctx, { activeOnly: true })` returns non-terminal envelopes. These can be subscribed to from the UI or read inside other Convex functions. Completion callbacks are internal mutations registered via `zsign.onCompleted(ctx, internal.myFunctions.onEnvelopeCompleted)`, called from a drain action such as a cron. Each callback is deduped and persisted; failures are recorded with `lastError` and retried on the next drain, giving at-least-once delivery semantics.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by zsign is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40zsign%2Fconvex)
- [GitHub repository](https://github.com/azlabsio/zsign-plugin)
- [Live demo](https://github.com/azlabsio/zsign-plugin/tree/main/example)
- [Convex Components Directory](https://www.convex.dev/components/zsign/convex)
- [Convex documentation](https://docs.convex.dev)