n8n Integration

n8n is a self-hostable workflow automation tool. Connect Konvoq to n8n using webhooks and API keys — no per-task pricing, full data ownership, 400+ supported apps.

Works today — no special n8n node required. Uses standard Webhook + HTTP Request nodes.

---

Before you start

You need:

• An active Konvoq workspace
• A running n8n instance (self-hosted or n8n Cloud)

---

Step 1 — Create an API key

1. Go to Dashboard → Settings → API Keys
2. Click New API Key
3. Name it (e.g. n8n)
4. Select scopes your workflow needs:

Scope	When you need it
webhooks	Creating/managing webhook subscriptions
read:leads	Reading lead data via API
write:leads	Creating or updating leads from n8n
read:conversations	Fetching conversation data

5. Store the key as an n8n credential or environment variable: KONVOQ_API_KEY

warning

The raw key is shown only once at creation. Save it immediately.

---

Step 2 — Create a Webhook subscription

1. In n8n, create a new workflow
2. Add a Webhook node — set method to POST
3. Copy the webhook URL n8n gives you (e.g. https://your-n8n.com/webhook/konvoq-lead)
4. In Konvoq, go to Dashboard → Connect → Webhooks
5. Click Add Webhook
6. Paste the n8n webhook URL
7. Choose which events to send (e.g. lead.created)
8. Save — Konvoq immediately sends a test request

---

Step 3 — Extract payload data

Konvoq sends a JSON body like:

{
  "id": "evt_abc123",
  "type": "lead.created",
  "occurredAt": "2025-04-23T10:00:00Z",
  "payload": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "pipeline_stage": "new"
  }
}

Use a Set node to extract fields:

name   →  {{ $json.payload.name }}
email  →  {{ $json.payload.email }}
stage  →  {{ $json.payload.pipeline_stage }}

---

Step 4 — Verify HMAC signature (recommended)

Add a Code node right after the Webhook node to validate the request is from Konvoq before processing:

// n8n Code node — verify Konvoq HMAC signature
const crypto = require('crypto');

const secret = $env.KONVOQ_WEBHOOK_SECRET;
const timestamp = $input.first().headers['x-konvoq-timestamp'];
const signature = $input.first().headers['x-konvoq-signature'];
const body = JSON.stringify($input.first().body);

const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(timestamp + '.' + body)
  .digest('hex');

if (signature !== expected) {
  throw new Error('Invalid webhook signature');
}

return $input.all();

Store the signing secret (shown when you create the webhook in Konvoq) as the environment variable KONVOQ_WEBHOOK_SECRET.

---

Step 5 — Call Konvoq API from n8n (actions)

Use an HTTP Request node to create or update leads from n8n:

{
  "method": "POST",
  "url": "https://chat.konvoq.com/api/public/zapier/leads",
  "authentication": "genericCredentialType",
  "genericAuthType": "httpHeaderAuth",
  "headers": {
    "Authorization": "Bearer {{ $env.KONVOQ_API_KEY }}"
  },
  "body": {
    "name": "={{ $json.name }}",
    "email": "={{ $json.email }}",
    "pipeline_stage": "new"
  }
}

---

Available API endpoints

Base URL: https://chat.konvoq.com — all endpoints require Authorization: Bearer YOUR_API_KEY.

Method	Endpoint	What it does	Required scope
GET	/api/public/zapier/me	Verify API key — returns your email	any
GET	/api/public/zapier/leads	Search leads by ?email= or ?name=	read:leads
POST	/api/public/zapier/leads	Create a new lead	write:leads
PUT	/api/public/zapier/leads/:id/stage	Update lead pipeline stage	write:leads
GET	/api/public/zapier/sessions	List recent handoff sessions	read:conversations
POST	/api/public/zapier/messages/:id	Send message to a handoff session	write:conversations

---

Import a ready-made workflow

Copy this JSON and import via n8n → Workflows → Import from JSON:

{
  "name": "Konvoq → Slack on New Lead",
  "nodes": [
    {
      "name": "Konvoq Webhook",
      "type": "n8n-nodes-base.webhook",
      "parameters": {
        "httpMethod": "POST",
        "path": "konvoq-lead",
        "responseMode": "onReceived"
      }
    },
    {
      "name": "Extract Lead Data",
      "type": "n8n-nodes-base.set",
      "parameters": {
        "values": {
          "string": [
            { "name": "name", "value": "={{ $json.payload.name }}" },
            { "name": "email", "value": "={{ $json.payload.email }}" },
            { "name": "stage", "value": "={{ $json.payload.pipeline_stage }}" }
          ]
        }
      }
    },
    {
      "name": "Slack",
      "type": "n8n-nodes-base.slack",
      "parameters": {
        "channel": "#leads",
        "text": "New lead: {{ $json.name }} ({{ $json.email }}) — Stage: {{ $json.stage }}"
      }
    }
  ]
}

More workflow templates (Google Sheets, handoff alerts) are available in the Konvoq GitHub repository.

---

Troubleshooting

Problem	Fix
Webhook not receiving events	Verify the URL in Dashboard → Connect → Webhooks is the correct n8n webhook URL
Signature verification failing	Check KONVOQ_WEBHOOK_SECRET matches the secret shown in Konvoq's webhook settings
401 Unauthorized from API calls	Verify KONVOQ_API_KEY is set and has the right scopes
Workflow not triggering	Ensure the webhook subscription in Konvoq is active (toggle in webhook settings)