Public API and signed webhooks for developers

The desk is a UI on top of envelopes. If your own systems already know who should sign, you should not re-type that into a form. Inkpacket’s public API lets owners and admins create a draft from a workspace template, fill fields, send a link, and then void, correct, or resend on the same envelope id. Signed webhooks POST the lifecycle back to a URL you choose.

This guide matches Docs and Docs. The marketing versions are API and webhooks and outbound webhooks. Tokens never cross workspaces. Successful calls update the token’s last-used time.

How authentication works

Mint an org-scoped token in Settings. Send it as Authorization: Bearer ip_…. Members cannot mint tokens; owners and admins can. A token from workspace A cannot list or send envelopes in workspace B. If a token leaks, revoke it in Settings and mint another.

On create and send, send an Idempotency-Key header if your client may retry. The same key with the same body returns the original response. A different body with the same key returns 409. That is how you avoid a double send when a worker crashes after the HTTP response is lost.

The envelope routes

Everything sits under /api/v1/packets. Desk help lists the same table; this is the narrative version.

• GET /api/v1/packets — list envelopes in the current organization.
• POST /api/v1/packets — create a draft from a template (templateId, optional title, field values, and per-packet webhook URL).
• GET /api/v1/packets/:id — get one envelope, including fields and signers.
• POST /api/v1/packets/:id/fill — fill existing field values by id or label.
• PUT /api/v1/packets/:id/fields — replace field marks on a draft.
• POST /api/v1/packets/:id/send — send when the envelope has fields and the plan still has envelopes. Optional accessCode hashes at rest and is returned once. The response includes signingUrl and embedUrl.
• POST /api/v1/packets/:id/void — void a sent envelope (optional reason).
• POST /api/v1/packets/:id/resend — resend the existing signing email without a new envelope.
• POST /api/v1/packets/:id/correct — update the outstanding recipient on the same envelope.

Create-from-template is the intended write path. Save the PDF and marks on the desk first — templates that reuse field layouts — then pass that templateId. Fill known values (a title, a date you already have) before send so the signer only completes what they must.

Send options you already know from the desk

Send accepts an optional access code. Inkpacket hashes it and returns the plaintext once for your client to copy. Share it on a second channel. Access codes is the operator guide. The response’s embedUrl is what you iframe; embedded signing explains the allowlist and postMessage events.

Void, correct, and resend keep the same envelope id. Do not create a second draft because an invite failed. The envelope admin guide is the product explanation of those three verbs.

Signed webhooks

Set a workspace webhook URL in Settings, or pass webhookUrl on create or send. Inkpacket POSTs JSON when an envelope is sent, viewed, signed, completed, expired, declined, voided, or corrected. The first POST is immediate. Failed deliveries retry on the hourly job, up to 5 attempts, then the row is marked failed. Settings keeps a delivery log. There is no test-send or replay button.

Each request includes X-Inkpacket-Event and X-Inkpacket-Signature as t=<unix>,v1=<hex>. Verify with HMAC-SHA256 of timestamp.body using the workspace signing secret. Reject stale timestamps. Rotate the secret in Settings if it leaks.

What to do with a delivery

1. Read the signature header. Split t and v1.
2. Compute HMAC-SHA256 of timestamp + "." + raw body with the signing secret.
3. Compare the hex digest to v1 in constant time.
4. If it matches, switch on the event and update your own record for that envelope id.
5. Return 2xx quickly. Work that can wait should run after you acknowledge.

Do not use iframe postMessage as your server-side source of truth. The parent tab can lie; the signed POST cannot if you verify it. Embed events are for UI. Webhooks are for systems.

Limits that will surprise you once

• Send checks the monthly envelope count for the workspace plan. Free is 5. See choosing a plan.
• POST /send accepts recipients and routingMode (SEQUENTIAL or PARALLEL). A single name and email still works. See More on signing order.
• One decline closes the whole envelope, even when later sequential signers have not been invited yet.
• Completed envelopes cannot be voided.
• Tokens are org-scoped. There is no global “platform” key in this foundation.
• Billing checkout is not open. The API still enforces plan envelopes.

A typical integration flow

1. Save the PDF and marks as a workspace template on the desk.
2. Mint a token in Settings. Store it as a secret, not in a frontend bundle.
3. POST /api/v1/packets with templateId, a title, and an optional per-packet webhookUrl.
4. POST /fill for values you already know. Leave signature marks for the signer.
5. POST /send with an Idempotency-Key, optional accessCode, and recipients / routingMode when more than one person must sign.
6. Hand signingUrl to email you already send, or embedUrl to a host page.
7. Verify each webhook. Update your record. Do not poll the list unless you are debugging.

Last-used time on the token is how you notice a forgotten key. If a worker has been silent for a month, rotate. If you run more than one environment, mint a token per workspace — staging should not share production’s secret or webhook URL.

If you are still evaluating the category, what electronic signature software is is the pillar. If you just need a human to send one PDF, use the desk. If your stack already has the recipient list, mint a token, create from a template, send with an Idempotency-Key, and verify the signature header on the way back.