key option or store it on the account. SignWell reads it from the X-Api-Key header.
Things to know before you send:
- Sending notifies real people.
documents.createanddocuments.createFromTemplatenotify every recipient unless you setdraft: true.bulkSends.createhas no draft or test mode: it sends every row as soon as it is created. Test mode keeps a document out of billing and makes it non-binding, but the notifications still go out. - Test mode does not follow a draft. SignWell documents that a document created in test mode is not automatically sent in test mode. The document routes (
documents.create,documents.createFromTemplate,documents.send) accepttest_mode, and the plugin also setsX-TestMode-Enabledso the two never disagree. - Recipient ids change meaning. At creation,
recipients[].idis the number you assign to attach fields. After the document exists, the id comes fromdocuments.get, anddocuments.updateRecipientsneeds that one. - Only unsigned recipients can change. Updating a recipient or their passcode fails with a 409 once that recipient has started signing.
- Completed files come back as a URL. SignWell returns a PDF or ZIP body by default, which this plugin cannot hand back intact, so
documents.getCompletedPdfanddocuments.getNom151Certificateask forurl_onlyand returnfile_url. - Webhooks. Register a URL with
webhooks.create, then give the returned id to the plugin aswebhookSecret(or store it as the account’s webhook signature). SignWell signs each delivery with HMAC-SHA256 overevent.type@event.time, keyed with that id; a delivery whose hash does not match is refused. - What the signature covers. The hash covers the event type and its timestamp, not the document body, so it stops an unsigned sender but not a replay of a genuine envelope. Treat a delivery as a notification to go read the document, not as the document’s final state.
- Paging.
bulkSends.listandbulkSends.getDocumentspage by number and reportnext_page.webhooks.listdoes not page.
- 28 typed API operations
- 10 incoming webhook event types
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the SignWell API key before the first call: More: API Key
pnpm corsair setup --plugin=signwell --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
Read a document and its recipientsWebhooks
This plugin registers 10 webhook event types. Configure the provider to POST to your Corsair HTTP handler, then usewebhookHooks on the plugin factory.
See Webhooks for every event path and payload shape, and Webhooks concept for routing.
What’s next
API reference
Every
signwell.api.* operation with input and output types.Webhooks
Event paths, payloads, and
webhookHooks examples.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.