Description

n8n-nodes-firma

n8n community node for Firma.dev — electronic signature and document signing API.

96 operations across 10 resources + a webhook trigger node. Fully declarative, zero runtime dependencies.

Installation

Community Nodes (recommended)

1. Go to Settings > Community Nodes
2. Select Install
3. Enter n8n-nodes-firma
4. Agree to the risks and select Install

From the Workflow Editor

You can also install the node without leaving your workflow:

1. Open any workflow and click + to add a node
2. Search for Firma in the node search panel
3. If the node is not yet installed, n8n shows it under Community Nodes in the search results with an Install option
4. Select it to install and add it to your workflow in one step

Manual Installation

cd ~/.n8n/nodes
npm install n8n-nodes-firma

Restart n8n after installation.

Authentication

1. In Firma, go to Workspace Settings > API
2. Copy your API Key
3. In n8n, create a new Firma API credential
4. Paste your API key

The credential defaults to https://api.firma.dev. Select Custom environment only for self-hosted or staging instances.

Webhook Secret (optional)

If you plan to use the Firma Trigger node, add your webhook secret to the credential for payload signature validation:

1. In Firma, go to Workspace Settings > Webhooks (or Company Settings > Webhooks for company-level secrets)
2. Enable webhooks if not already enabled. A secret is automatically generated when you turn webhooks on
3. Copy the Webhook Secret using the show/copy controls on that page
4. In your n8n Firma API credential, paste the secret into the Webhook Secret field

If you need to rotate the secret later, use the Regenerate button. Firma keeps the old secret valid for a 7-day grace period, so existing integrations continue working while you update credentials.

Without a secret, the trigger node will still receive events but cannot verify that payloads genuinely came from Firma. See the Webhooks guide for full setup, including enabling webhook delivery and configuring event subscriptions.

Resources and Operations

| Resource | Operations | Description |
|—|—|—|
| Signing Request | List, Create, Create and Send, Get, Update (partial/full), Documents (add/update/reorder/remove/download), Send, Cancel, Resend, Download, Get Audit, Get Users, Get Fields, Get Reminders, Delete, Remove Seal Participant, Custom Fields (list/create/delete) | Core signing workflow |
| Template | List, Create, Get, Update (partial/full), Delete, Duplicate, Replace Document, Documents (add/update/reorder/remove), Get Fields/Users/Reminders, Custom Fields (list/create/delete) | Reusable document templates |
| Document | Upload | Upload a PDF or DOCX file (up to 50 MB) and get a document ID for creates and document operations |
| Organization Seal | List, Get, Get Image, Get Access Log, Get Applications, Revoke | Read and revoke organization seals |
| Webhook | List, Create, Get, Update, Delete, Test, Rotate Secret (company/workspace), Secret Status (company/workspace) | Webhook management |
| Workspace | List, Create, Get, Update (partial/full), Get/Update Settings, API Key Regenerate/Expire, Custom Fields (list/create/update/delete) | Workspace administration |
| Company | Get, Update (partial/full) | Company details (name, account owner, website, language) |
| Domain | List, Add, Get, Delete, Verify DNS, Verify Ownership, Finalize, Set Primary (company and workspace scopes) | Custom domain management |
| Email Template | List, Upsert, Delete (company/workspace), Get Defaults, Get Placeholders | Email template customization |
| JWT | Generate/Revoke Template Token, Generate/Revoke Signing Request Token | Embedded editor/signing tokens |

Trigger Node

The Firma Trigger node starts a workflow when a Firma event occurs. It offers 34 webhook events, 26 of which Firma sends:

• Signing Request: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent, field filled, document updated
• Recipients: added, signed, declined, updated, identity changed
• Seals on signing requests: seal applied, seal paused, seal swapped
• Organization Seals: created, updated, deleted, erased
• Templates: created, updated, deleted, field added*, used
• Workspaces: created, updated, deleted*
• Domains: verified, verification failed

* Shown as (Not Sent) in the event list: the API accepts these subscriptions, but Firma does not currently send these events. They stay in the list so workflows that already selected them keep loading.

The trigger looks for a webhook it registered earlier (same URL, same workspace) before creating a new one, so a restarted workflow reuses its subscription.

HTTPS Required

Firma’s webhook API requires HTTPS URLs. For local development, use a tunnel service:

Using cloudflared
cloudflared tunnel --url http://localhost:5678
Using ngrok
ngrok http 5678

Webhooks Must Be Enabled

Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, enable webhooks for your workspace in the Firma dashboard (Workspace Settings > Webhooks). The per-webhook Test button bypasses this switch, so a successful test does not confirm real events will deliver. See the Webhooks guide for details on enabling delivery and managing event subscriptions.

Signature Validation

If a webhook secret is configured in the credential, the trigger node validates the X-Firma-Signature header using HMAC-SHA256. It also supports X-Firma-Signature-Old for secret rotation grace periods.

Important Notes

No Auto-Retry on Write Operations

Firma’s write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. Set Retry On Fail to off for workflows that use these operations.

Document Upload

With Document Source: Binary File, the document is sent as base64 inside the JSON request. Requests over 6 MB answer 413, which a PDF reaches at roughly 4.5 MB. For larger files, and for multi-document requests, run Document > Upload first (PDF or DOCX, up to 50 MB) and pass the returned document_id to the create (Uploaded Document IDs takes up to 20, in document order) or to Add Document.

• An upload ID is consumed by the create that uses it: upload once per create.
• An upload that is never used expires after one hour. Retry On Fail on Document > Upload leaves such unused uploads behind; they are harmless.
• Uploaded Document IDs on a create: more than one ID answers 409 MULTIDOCUMENTREAD_ONLY for a company that is not on the multi-document path or while its multi-document editing is suspended.
• The document operations (Add, Update, Reorder, Remove and Download Document) answer 404 for a signing request or template on the single-document path, and 409 MULTIDOCUMENTREAD_ONLY while its multi-document editing is suspended.

Template Seals on Create

Since Firma API 01.39.01, a signing request created from a template inherits the template’s organization seals and their seal-owned fields. Such a create can answer 409 SEALUNAVAILABLE (a template seal was revoked or deleted) or 503 SEALSDISABLED (seals are not enabled). Turn on Create Without Template Seals to create without them, or set Seal Participants to replace them; seal participants and recipients share one signing order.

Upgrading from 0.1.x

0.2.0 fixes operations that the API refused in 0.1.x. Saved workflows keep loading; a few need a value they did not have:

• Company > Update (Full) now requires Account Owner, Account Owner Email and Website (the API requires all four fields).
• JWT > Revoke … Token takes the JWT ID from the generate output (jwtrecordid for templates, jwt_id for signing requests), not the token itself.
• Create Custom Field on signing requests and templates creates a field definition: Field Label is sent as the label, and the old Field Value parameter is gone (the API has no value there). On workspaces, Field Value is the field’s preset value.
• Email Template > Upsert needs both Subject and Body.

Download Returns a URL

The Download operation returns a signed URL and metadata, not binary data. Use an HTTP Request node to fetch the actual file from the download_url.

Example Workflows

Send a signing request from a template

1. Firma node: Create and Send operation with template_id, recipient name and email
2. Firma Trigger node: listen for signing_request.completed
3. Process the completed signing request data

Monitor signing progress

1. Firma Trigger: listen for signing_request.recipient.signed
2. IF node: check if all recipients have signed
3. Firma: Download the completed document

Resources

• Firma API Documentation
• Firma Dashboard
• n8n Community Nodes Documentation

License

MIT