n8n

1. Firma node (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. Firma Trigger node — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. signing_request.completed).
3. AI Agent tool — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

​

Prerequisites

• A Firma account with an API key
• An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
• At least one Firma template with signing fields configured

​

Install the community node

​

From Settings

1. In n8n, go to Settings > Community Nodes
2. Click Install
3. Enter n8n-nodes-firma
4. Agree to the risks and click Install

​

From the Workflow Editor

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

​

Set up credentials

1. In the n8n editor, click the Credentials icon in the left sidebar
2. Click Add Credential and search for Firma API
3. Set the fields:
   • API Key: paste your Firma workspace API key (found in Workspace Settings > API)
   • Webhook Secret (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to Workspace Settings > Webhooks (or Company Settings > Webhooks) and copy the secret using the show/copy controls. If you need to rotate the secret later, click Regenerate; the old secret stays valid for a 7-day grace period. See the webhooks guide for full setup.
4. Leave Environment set to Production unless you are connecting to a self-hosted or staging instance
5. Click Save

​

Path 1: Firma node

​

Send a signing request from a template

1. Add a Firma node to your workflow
2. Select your Firma API credential
3. Set Resource to Signing Request and Operation to Create and Send
4. Fill in:
   • Name: a name for the signing request (e.g. {{ $json.contract_name }})
   • Document Source: Template
   • Template ID: the ID of your Firma template
5. Under Recipients, click Add Recipient and fill in:
   • Email: {{ $json.signer_email }}
   • First Name: {{ $json.signer_first_name }}
   • Designation: Signer
   • Order: 1
6. Optionally expand Additional Fields to set language or expiration, and Settings to control download permissions, OTP verification, or email notifications

​

Create a draft first, then send after approval

1. Use the Create operation (creates a draft, does not send)
2. Add an n8n Wait or approval node in the middle of your workflow
3. Use the Send operation in a later node, passing the signing request ID from the Create step

​

Other common operations

​

Wire it into a trigger

• Form Trigger > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
• Webhook Trigger > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
• Schedule Trigger > database query > Firma: nightly batch of renewal contracts goes out automatically

​

Path 2: Firma Trigger node

​

Set up a trigger

1. Create a new workflow and add a Firma Trigger node as the trigger
2. Select your Firma API credential
3. In Events, select which events to listen for (e.g. Signing Request Completed, Signing Request Recipient Declined)
4. Optionally set Workspace ID to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

​

Available events

• 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
• Templates: created, updated, deleted, field added, used
• Workspaces: created, updated, deleted
• Domains: verified, verification failed

​

Branch on event type

• signing_request.completed > update a record in your CRM, send a confirmation email, kick off provisioning
• signing_request.recipient.declined > notify sales
• signing_request.expired > re-send or move the deal to lost

​

Signature validation

​

HTTPS required

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

# Using ngrok
ngrok http 5678

​

Path 3: Firma as a tool for the n8n AI Agent

1. In your AI Agent workflow, add a Firma node as a tool input on the agent
2. Select your Firma API credential
3. Choose which resource and operation to expose (e.g. Signing Request > Create and Send)

• One for Template > List (so the agent can find the right template)
• One for Signing Request > Create and Send (so it can send documents)
• One for Signing Request > Get (so it can check status)

​

Embedded signing

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

​

Using the HTTP Request node instead

​

Create a Header Auth credential

1. In the n8n editor, click the Credentials icon in the left sidebar
2. Click Add Credential and search for Header Auth
3. Set the fields:
   • Name (credential name): Firma API
   • Name (header): Authorization
   • Value: paste your Firma API key
4. Click Save

​

Send a signing request

{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}

​

Receive webhooks without the community node

1. Create a new workflow with a Webhook node as the trigger. Set HTTP Method to POST and copy the Production URL.
2. In the Firma dashboard, go to Settings > Webhooks, click Add webhook, paste the n8n production URL, and select your events.
3. Add a Switch node after the Webhook trigger to route on {{ $json.body.type }}.

​

Bonus: MCP connection for AI-assisted building

https://docs.firma.dev/mcp

​

Next steps

• API authentication — API keys and workspace scoping
• Webhooks guide — event types, payloads, and signature verification
• Embedded signing — in-app signing experience
• Creating workspaces — multi-tenant setups for SaaS apps
• Complete setup guide — end-to-end Firma integration walkthrough
• API reference — full endpoint documentation