Connect n8n to KirokuForms

Prerequisites

• An n8n instance (Cloud or self-hosted)
• A KirokuForms account with at least one active form
• A KirokuForms API key with appropriate scopes — generate one from the API Keys page:
  • submissions:read — read submission data
  • submissions:write — create/update submissions
  • hitl:create — approve or reject submissions
• Self-hosted n8n: your instance must be publicly accessible (or tunneled) for KirokuForms webhooks to reach it

Option A: Receive Webhooks in n8n

Use this approach when you want n8n to react to events in KirokuForms (new submissions, approvals, rejections).

Step 1: Add a Webhook Node

1. Create a new workflow in n8n.
2. Add a Webhook node as the trigger.
3. Set HTTP Method to POST.
4. Set a path (e.g., /kirokuforms-webhook).
5. Copy the Production URL shown in the node (it looks like https://your-n8n.app.n8n.cloud/webhook/kirokuforms-webhook).
6. Set Response Code to 200.

Step 2: Configure the Webhook in KirokuForms

1. Go to your KirokuForms dashboard and select the form.
2. Navigate to Settings > Webhooks.
3. Click Add Webhook and paste the n8n production URL.
4. Select the events you want to receive:
   • submission.created — new form submissions
   • decision.approved — approved submissions
   • decision.rejected — rejected submissions
5. Optionally set a webhook secret for signature verification.
6. Enable the webhook and save.

Step 3: Test and Verify

1. In n8n, click Listen for test event on the Webhook node.
2. In KirokuForms, click the Test button on your webhook configuration.
3. n8n will display the received payload. The structure looks like:

{
  "eventType": "form.submission.new",
  "formId": "frm_abc123xyz789",
  "submissionId": "sub_def456uvw012",
  "timestamp": "2026-04-01T10:30:00Z",
  "data": {
    "name": "Arthur Dent",
    "email": "arthur.dent@example.com",
    "feedback_topic": "General Inquiry",
    "message": "What is the answer to life, the universe, and everything?"
  },
  "metadata": {
    "submittedVia": "web"
  }
}

Step 4: Add Processing Nodes

After the webhook trigger, connect any n8n nodes you need:

• Google Sheets — append a row with submission data
• Slack — send a notification message
• Send Email — notify a team member
• Airtable — create a record
• HTTP Request — call any external API
• IF — branch logic based on submission data

Reference fields using n8n expressions like {{ $json.body.data.name }} or {{ $json.body.submissionId }}.

Option B: Call the KirokuForms API from n8n

Use this approach when you want n8n to push data into KirokuForms — for example, creating submissions from another source or approving/rejecting submissions programmatically.

Set Up API Credentials

1. In n8n, go to Credentials > Add Credential.
2. Choose Header Auth.
3. Set Name to Authorization.
4. Set Value to Bearer YOUR_API_KEY (replace with your actual key).
5. Save the credential — you can reuse it across multiple HTTP Request nodes.

Create a Submission

Add an HTTP Request node with these settings:

• Method: POST
• URL: https://www.kirokuforms.com/api/v1/submissions
• Authentication: select your Header Auth credential
• Send Headers: add Idempotency-Key with a unique value
• Send Body: JSON with formId and your form fields

curl -X POST "https://www.kirokuforms.com/api/v1/submissions" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: unique-request-id-123" \
     -d '{
           "formId": "YOUR_FORM_ID",
           "name": "Jane Doe",
           "email": "jane@example.com",
           "message": "Submitted via n8n"
         }'

A successful response (201):

{
  "success": true,
  "data": {
    "submissionId": "sub_xyz789abc456",
    "taskId": null,
    "timestamp": "2026-04-01T12:00:00Z"
  },
  "message": "Submission created"
}

Approve or Reject a Submission

Add another HTTP Request node targeting the decision endpoints:

• POST /api/v1/submissions/{submissionId}/approve
• POST /api/v1/submissions/{submissionId}/reject

curl -X POST "https://www.kirokuforms.com/api/v1/submissions/SUBMISSION_ID/approve" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json"

Example Workflows

1. New Submission to Google Sheets + Slack

Nodes in order:

1. Webhook — receives KirokuForms submission.created event
2. Google Sheets — appends data.name, data.email, submissionId as a row
3. Slack — sends a summary message to #submissions

2. Typeform Responses Create KirokuForms Submissions

Nodes in order:

1. Typeform Trigger — new response received
2. Set — map Typeform fields to KirokuForms field names
3. HTTP Request — POST to /api/v1/submissions

3. Auto-Approve Based on Criteria

Nodes in order:

1. Webhook — receives submission.created
2. IF — check data.feedback_topic equals "General Inquiry"
3. HTTP Request (true branch) — POST to /api/v1/submissions/{submissionId}/approve
4. Slack (false branch) — notify team for manual review

4. Daily Digest of Submissions

Nodes in order:

1. Cron — runs daily at 9:00 AM
2. HTTP Request — GET recent submissions via KirokuForms API
3. Summarize — aggregate counts and key fields
4. Send Email — deliver the digest to the team

Troubleshooting

• n8n webhook not receiving data: Make sure you're using the production URL (not the test URL) in KirokuForms, and that your n8n workflow is active. For self-hosted n8n, verify the instance is publicly reachable.
• 401 Unauthorized on API calls: Check that your API key is valid and has the required scopes. The Header Auth credential value must include the Bearer prefix.
• 422 Validation Error: The submission payload does not match the form's expected fields. Check the details array in the error response for specific field errors.
• Duplicate submissions: Always include an Idempotency-Key header when creating submissions via the HTTP Request node.
• Self-hosted n8n behind a firewall: Use a tunneling service (e.g., ngrok, Cloudflare Tunnel) during development, or configure your firewall to allow inbound POST requests from KirokuForms.