n8n-nodes-repu

Community node package cho n8n self-host. V1 cung cấp node HubSpot Form Submission Trigger để poll submission mới từ một HubSpot form.

Tính năng V1

• Poll một HubSpot form theo interval cố định 5 phút.
• Dùng HubSpot Private App token qua credential của n8n.
• Có test connection để kiểm tra token ngay trong credential.
• Tải danh sách HubSpot Forms để chọn bằng dropdown, không cần nhập Form ID thủ công.
• Chuẩn hóa form submission thành JSON dễ map trong workflow.
• Chống trùng bằng workflow static data.
• Có tùy chọn lấy raw payload HubSpot.
• Cấu trúc package sẵn sàng mở rộng thêm LarkBase node sau này.

Cài đặt trong n8n self-host

Trong n8n, vào Settings → Community nodes → Install, nhập package name:

n8n-nodes-repu

Sau đó restart n8n nếu node chưa xuất hiện trong node picker.

Build local

npm install
npm run build

Credential HubSpot

Tạo HubSpot Private App trong HubSpot:

1. Vào Settings → Integrations → Private Apps.
2. Tạo Private App mới.
3. Cấp scope đọc dữ liệu forms/submissions phù hợp với HubSpot portal của bạn.
4. Copy Access Token.
5. Trong n8n, tạo credential HubSpot Private App API.
6. Dán token vào trường Access Token.
7. Bấm test connection để kiểm tra token trước khi dùng node.

Token không được hardcode trong workflow hoặc code. Token chỉ lưu trong credential vault của n8n.

Node: HubSpot Form Submission Trigger

Node này poll một HubSpot form và emit item khi có submission mới.

Input

Node poll HubSpot mỗi 5 phút. Interval này được cố định để UI gọn và dễ dùng.

First Run Mode

• From Activation: chỉ lấy submission mới sau lúc kích hoạt workflow.
• From Custom Date: lấy submission mới hơn ngày bạn chọn.
• Fetch Recent Then New: lần đầu lấy batch gần nhất, sau đó chỉ lấy submission mới.

Output example

{
  "submissionId": "abc123",
  "formId": "form-guid",
  "submittedAt": "2026-05-04T09:00:00.000Z",
  "submittedAtUnix": 1777885200000,
  "fields": {
    "email": "lead@example.com",
    "firstname": "Nguyen",
    "phone": "0900000000"
  },
  "contact": {
    "email": "lead@example.com"
  },
  "page": {
    "url": "https://example.com/contact",
    "title": "Contact"
  },
  "context": {
    "ipAddress": "1.2.3.4",
    "hutk": "hubspotutk"
  },
  "raw": {}
}

Ví dụ workflow

HubSpot Form Submission Trigger
→ LarkBase Create Record
→ Slack/Email notification

Map field trong n8n:

Email = {{ $json.fields.email }}
Phone = {{ $json.fields.phone }}
Name  = {{ $json.fields.firstname }}

Chống trùng dữ liệu

Node lưu cursor trong workflow static data:

lastSeenSubmittedAtUnix
seenSubmissionIds

Cursor không lưu PII như email, phone, name hoặc message.

Lưu ý: nếu duplicate workflow hoặc reset static data, submission cũ có thể được emit lại tùy First Run Mode.

Bảo mật và PII

• Không hardcode token trong code.
• Không log token.
• Không lưu PII trong cursor.
• Nếu bật Include Raw Data, output có thể chứa PII từ HubSpot.
• Chỉ cấp scope HubSpot tối thiểu cần thiết.
• Giới hạn quyền truy cập workflow có chứa lead data.

Troubleshooting

Không thấy node trong n8n

• Kiểm tra package đã build chưa: npm run build.
• Kiểm tra n8n đã restart chưa.
• Kiểm tra package name bắt đầu bằng n8n-nodes-.
• Kiểm tra package.json có field n8n.nodes và n8n.credentials.

Lỗi token

• Kiểm tra Private App token còn hiệu lực.
• Dùng test connection trong credential để xác minh token.
• Kiểm tra token đã copy đúng.
• Kiểm tra scope đọc forms/submissions.
• Kiểm tra form thật sự có submission mới.
• Nếu chọn From Activation, submission cũ trước lúc bật workflow sẽ không emit.
• Thử manual run với Fetch Recent Then New để kiểm tra data.

Bị trùng event

• Tăng Dedupe Window Size.
• Không duplicate workflow khi chưa hiểu cursor behavior.
• Không reset workflow static data nếu không muốn replay.

Rate limit

• Node đang poll cố định mỗi 5 phút.
• Giảm số workflow cùng poll HubSpot.
• Giảm Limit nếu portal có traffic thấp.

Roadmap

• 0.1.1: Thêm credential test, form dropdown và cố định poll interval 5 phút.
• 0.1.0: HubSpot Form Submission Trigger.
• 0.2.0: LarkBase Record node.
• 0.3.0: LarkBase Search/Update node.
• 0.4.0: LarkBase Trigger node.

Development notes

Package được tổ chức theo service folder:

nodes/HubSpot/...
utils/hubspot/...
credentials/...

Sau này thêm LarkBase:

nodes/LarkBase/...
utils/larkbase/...
credentials/LarkBaseApi.credentials.ts