An independent n8n community-node package for connecting Twenty CRM workflows to standard and custom objects, metadata-driven records, and signed record-event webhooks.
This is an unofficial Black Swamp AI community integration. It is not affiliated with, sponsored by, endorsed by, or maintained by Twenty.com, PBC. The Twenty name and logo belong to their respective owner(s) and are used only to identify compatibility.
Installation · Compatibility · Credentials · Operations · Troubleshooting · Black Swamp AI
Install the verified community node from the n8n editor:
- Open the Canvas, then open the nodes panel.
- Search for Twenty CRM.
- Select More from the community, then choose Install.
See n8n's verified community-node installation guide for current requirements.
Self-hosted administrators who need the package fallback can install the exact package
@blackswampai/n8n-nodes-twentycrm through the instance's supported community-node management.
For development, use Node.js 22.22.0 or newer, clone the repository, then run npm ci, npm run build, and npm run smoke:install.
Releases are published by the repository's tag-only GitHub Actions workflow with an SLSA provenance attestation, which traces the package to the repository and commit it was built from. Verify the Provenance record on the npm package page or inspect the published attestations directly:
npm view @blackswampai/n8n-nodes-twentycrm dist.attestationsThe package supports configurable Twenty Cloud and self-hosted root URLs. Metadata discovery has regression coverage for the legacy Twenty v2.9 and modern v2.35 GraphQL shapes; the retained automated live API harness remains pinned to v2.9.0 by immutable image digest. The package declares Node.js >=22.22.0 and n8n-workflow as a host-provided peer.
This is not a broad Twenty or n8n version matrix. The package is available through n8n's verified community-node discovery; this status does not expand the runtime compatibility evidence above. See Compatibility and qualification, the API matrix, and the UI qualification checklist.
Twenty API requires a Twenty API key and root Base URL. It sends Bearer authentication through n8n's credential helper. The default is https://api.twenty.com; self-hosted users enter their installation root, including any reverse-proxy prefix. Pasted /rest, /graphql, /metadata, and /rest/metadata suffixes are normalized centrally.
The credential test sends a minimal read-only Core GraphQL query. The API-key role needs access to every object used by a workflow. Dynamic schema discovery needs metadata access; the local custom-schema qualification additionally requires the Data Model settings permission.
Twenty Webhook API stores the shared webhook secret as a password-masked value. Its credential test confirms only that a non-empty secret is configured; verify signed delivery by sending a Twenty event. Enter the same strong secret in Twenty's webhook form even though Twenty labels it optional. Unsigned trigger delivery is not supported.
Never place API keys or webhook secrets in workflow fields, source code, logs, or issue reports.
The action node provides:
- Company, Person, Opportunity, Task, and Note: Create, Get, Get Many, Update, and Delete.
- Record: the same generic CRUD surface for active standard and custom workspace objects.
- Schema Object: read-only Get and Get Many metadata discovery.
Create and Update default to metadata-driven Field Mapping. Fixed resources show common fields first and keep remaining writable/custom fields under Additional Fields. Generic Record retains full dynamic schema ordering. Known compound values are reconstructed for Twenty's REST API; JSON input remains available as an advanced fallback. Get Many supports bounded Limit/Return All cursor pagination and raw Twenty REST filter/order expressions.
All resources reuse shared authenticated transport, pagination, field mapping, and sanitized errors. Fixed-resource REST routing uses stable shared descriptors, so Get/Get Many and JSON-input CRUD do not depend on metadata discovery. Generic Record operations and every field-mapped write remain metadata-driven. Transient retries are conservative and idempotency-gated; record mutations are never automatically retried. Schema creation or modification is not exposed as a node operation.
The Twenty CRM Trigger receives Record Created, Record Updated, and Record Deleted events for one active standard/custom object or All Objects. Registration is manual:
- Choose Test URL only while n8n is listening for a test event; use Production URL for an active workflow.
- Create the webhook in Twenty under Settings → APIs & Webhooks.
- Enter a strong shared secret in Twenty and save the same value in
Twenty Webhook API.
The trigger verifies Twenty's HMAC-SHA256 signature over the exact raw request body and millisecond timestamp, requires delivery within a five-minute signed timestamp tolerance, and filters the all-events stream inside n8n. Automatic registration and unsigned mode are not supported.
See Troubleshooting for credential/network failures, dynamic fields, permissions, record errors, local Docker routing, and webhook signature failures.
- Twenty documentation
- n8n community node documentation
- Local Twenty harness
- Testing strategy and evidence
- Branding and icon provenance
- Black Swamp AI — Twenty CRM for n8n
- Project issues
- Release process
The packaged light and dark icons use the unmodified official Twenty 96×96 SVG, confirmed unchanged at twentyhq/twenty commit ee6a5c37cd9dc420934c02cf32256234f7e96d01. Use of that mark does not imply affiliation, sponsorship, or endorsement. See branding and icon provenance.
Project code is available under the MIT License. Third-party trademarks remain the property of their respective owners.