Production Checklist

Use this checklist to make sure your integration is secure, reliable, and ready for production.

Security

• Never expose secrets in client-side code — Keep API credentials, webhook signing secrets, and other secrets on your backend only.
• Use HTTPS everywhere — Use HTTPS for API requests, redirect URLs, and webhook endpoints.
• Request only the scopes you need — Use read, write, or read write based on what the integration actually does.
• Store tokens and sensitive data securely — Protect access tokens, refresh tokens, customer data, and webhook signing secrets at rest.
• Restrict access to signed documents — Only authorized users and systems should be able to view or download documents.

Webhooks

• Verify webhook signatures — Validate the X-Formify-Signature header using your webhook signing secret and the raw request body.
• Use the raw request body for verification — Do not verify against a re-serialized JSON payload.
• Check that the timestamp is recent — Validate X-Formify-Timestamp to reduce replay attacks.
• Make webhook handling idempotent — Store processed eventId values and safely ignore duplicates.
• Do not assume event ordering — Events may arrive late, more than once, or out of order.
• Return a 2xx response quickly — Acknowledge the webhook promptly and process longer tasks asynchronously if needed.

Reliability

• Handle expected HTTP errors — At minimum, handle 400, 401, 403, 404, 429, and 5xx responses.
• Use retries with backoff where appropriate — Retry temporary failures carefully instead of failing immediately.
• Handle rate limiting — If the API returns 429, use the rate limit headers to slow down and retry later.
• Log safely — Log request outcomes and webhook processing, but never log secrets or sensitive personal data.

Documents & files

• Validate PDF files before upload — Files must be PDFs, max 50 MB, not password-protected, and must not contain existing digital signatures.
• Store important Formify IDs — Keep fileId, documentId, draftId, signeeId, and webhookId values where your workflow needs them.
• Check account capabilities before using advanced signature types — Verify BankID, ID scan, and face liveness availability with GET /account/capabilities.
• Handle signed file redirects — Signed PDF downloads redirect to a time-limited URL. Follow the redirect immediately and request a new URL if it expires.

Before launch

• Test the full integration end-to-end — Verify the main production flow from API request to completed signing result.
• Test webhook signature verification — Confirm that valid webhook signatures are accepted and invalid ones are rejected.
• Test failure scenarios — Check behavior for expired tokens, invalid input, network failures, retries, and duplicate webhook deliveries.
• Verify production configuration — Confirm that production credentials, webhook endpoints, secrets, URLs, and environment settings are correct.
• Monitor critical failures — Set up alerts for repeated API failures or webhook delivery problems.

Client ID metadata document clients

If you are using a URL-based client_id (see OAuth for AI & Third-Party Clients):

• Serve your metadata document over HTTPS and ensure it responds quickly.
• Verify client_id matches the hosting URL exactly.
• Include a meaningful client_name and logo_uri — these are shown to users during authorization.
• Generate a fresh code_verifier for every authorization request and use S256.
• Use the state parameter for CSRF protection.
• Handle metadata caching — Formify caches your document. Allow time for changes to propagate.

DCR-registered clients

If you registered your client via Dynamic Client Registration:

• PKCE (S256) is mandatory for public clients — generate a fresh code_verifier for every authorization request.
• Public clients have no client_secret — protect your client_id and never embed it in untrusted environments unnecessarily.
• Confidential DCR clients: store client_secret securely — it is only returned once at registration time.
• DCR registration is rate limited — plan your registration flow accordingly.

AI & MCP clients

If users will connect Formify through an AI assistant or MCP client:

• Prefer OAuth/PKCE where the client supports it — users authorize access in Formify and can revoke it later under Settings → Integration → My applications.
• Review what the AI provider can see — document titles, recipient details, form values, and fetched PDF content may become part of the assistant's conversation context.
• Require human review for sensitive actions — confirm send, revoke, delete, reminder, webhook, and document download actions before relying on them in production workflows.
• Test common prompts against realistic data — verify that the assistant chooses the right Formify tools, fields, signers, and signature settings.
• Review optional skills before enabling them — if you install Formify Claude Skills or other assistant guidance, treat them as executable operational instructions and keep them versioned.

MCP clients using API key fallback

If an MCP client cannot use OAuth/PKCE and you connect it with a Formify API key:

• Use a purpose-specific key where possible — this makes it easier to rotate or revoke access for that MCP connection later.
• Keep the key in the client's token/secret field — do not paste it into prompts, logs, issue trackers, or shared documents.
• Rotate or revoke when access is no longer needed — the MCP server exchanges the key for short-lived Bearer tokens, but the API key itself should still be managed as a secret.