BlogTag
API and webhooks
Mint an org-scoped Bearer token, create envelopes from a template, and receive a signed JSON body when status changes.
Related product pages
Guides
Embedded signing on your own site
Iframe an Inkpacket signing token on a host page you already operate: /embed/sign/TOKEN, frame-ancestors, EMBED_ALLOWED_ORIGINS, and postMessage events for viewed, signed, and completed.
Public API and signed webhooks for developers
Mint an org-scoped Bearer token, create envelopes from a template, send with an optional access code, and verify HMAC-SHA256 webhook signatures on the envelope lifecycle.
API vs desk: who should send the envelope
When an ops team should send from the Inkpacket desk and when to mint a Bearer token: templates, Idempotency-Key retries, the monthly envelope cap, and mail, SMS, and checkout are not open without credentials.
Webhook retries explained
How Inkpacket delivers signed webhook POSTs: first attempt immediately, pending retries on the hourly envelope job, 5 attempts then failed, the last-12 log, and why there is no replay button.
Create an envelope from a template via the API
Mint an org-scoped Bearer token, POST /api/v1/packets with a templateId, fill known values, and send with an Idempotency-Key — one envelope toward the monthly cap. Free allows 5 packets a month.
Listen for envelope status webhooks
Subscribe to Inkpacket envelope events — sent, viewed, signed, completed, expired, declined, voided, corrected — verify HMAC-SHA256, and do not treat iframe postMessage as the server record.
Idempotency-Key on API sends
Send an Idempotency-Key on Inkpacket create, fill, fields, and send so a retried POST replays the original response. The same key with a different body returns 409. Void, resend, and correct do not use that header.
When webhook delivery fails
Inkpacket still sends the envelope when a webhook POST misses. Pending rows retry on the hourly job, up to 5 attempts, then failed. There is no replay button. Read the last-12 log, fix the URL, and wait for the next real event.
Mint and revoke API Bearer tokens
Owners and admins mint an Inkpacket ip_… secret once at Settings, send it as Authorization: Bearer, and revoke it by id. The token-mint revoke loop stores a SHA-256 hash, not the plaintext.
API fill then send
After POST /api/v1/packets with a templateId, POST /fill with known values, then POST /send. Fill is not send. Send is the envelope. That is fill-then-send honesty — not a one-shot create that pretends the draft already went out.
Webhook signature verify checklist
Verify Inkpacket webhooks as t=<unix>,v1=<hex> with HMAC-SHA256 of timestamp.body and the workspace signing secret. Reject a mismatch. That is signature-verify honesty — not a test-send button.
Idempotency-Key on create, fill, and send
Inkpacket accepts Idempotency-Key on create, fill, fields, and send. Use a different key per step. Reusing a create key on send returns 409. That is create-fill-send-key honesty — not one key for the whole worker.
Members cannot mint API tokens
Inkpacket members can send from the desk. They cannot mint or revoke org-scoped Bearer tokens. That is member-token honesty — not a plan gate, not a missing Settings page.
Why GET /api/v1/health needs no Bearer token
GET /api/v1/health is public. It does not take a Bearer token. A 200 there is not permission to POST envelopes. That is health-public honesty — flags, not a secret, not a member mint.
Why webhooks have no test-send
Inkpacket Settings shows the last 12 webhook deliveries. There is no test-send or replay button. Send an envelope after saving a URL. That is no-test-send honesty — not a missing Settings card.
Why Bearer token required is not Invalid API token
A missing Inkpacket Authorization header returns 401 Bearer token required. A bad or revoked token returns 401 Invalid API token. That is bearer-versus-invalid honesty — two 401s, not a 429, not health.
Why an API token never crosses workspaces
An Inkpacket Bearer token is org-scoped. A secret from workspace A is 401 Invalid API token on workspace B. That is token-workspace honesty — not a missing header, not a 429.
Why Settings only shows the last 12 webhook deliveries
Inkpacket Settings shows the last 12 webhook deliveries with status, attempt count, and last error. Older rows are not a plan unlock. That is webhook-log honesty — not a missing replay.
Why a webhook URL must be HTTPS
Inkpacket webhook URLs require HTTPS except on localhost or .test hosts. An http:// receiver is refused. That is webhook-https honesty — not a missing test-send, not checkout.
Why the API token is shown only once
Inkpacket shows the full ip_… API token once at mint. After that the list shows the prefix. That is token-once honesty — not a missing export, not checkout.
Why This envelope can no longer be edited is not a completed lock
Inkpacket returns This envelope can no longer be edited when fill or field replace hits a closed envelope. That is edit-lock honesty — not a completed-admin lock, not checkout.
Why This envelope has no fields to fill is not a published-form cap
Inkpacket returns This envelope has no fields to fill when API fill hits an envelope with zero marks. That is no-fields-fill honesty — not a Web Form cap, not checkout.
Why Provide at least one field value is not a published-form cap
Inkpacket returns Provide at least one field value when API fill hits an envelope that has marks but an empty body. That is empty-fill honesty — not no-fields-fill, not checkout.
Why Field X was not found on this envelope is not a published-form cap
Inkpacket returns Field X was not found on this envelope when API fill names an id or label that is not on the envelope. That is miss-fill honesty — not an empty body, not checkout.