n8n Integration

Overview

Renderly's n8n community node allows users to automate video rendering workflows using n8n's visual workflow builder. Users can create renders from their projects or public system templates with dynamic variable replacement, check render status, and receive instant webhook notifications when renders complete or fail.

Platform: n8n (open-source workflow automation)
Package: n8n-nodes-renderly
Auth: API Key (Authorization: Bearer <key>)
Base URL: https://renderly.video/api/v1

Architecture

n8n community nodes are TypeScript npm packages that follow n8n's node development conventions. The package exports credential types, regular nodes (actions), and trigger nodes (webhooks).

Structure

queue/integrations/n8n/
├── package.json                          # npm package with n8n metadata
├── tsconfig.json                         # TypeScript configuration
├── index.ts                              # Export entry point
├── credentials/
│   └── RenderlyApi.credentials.ts        # API key auth + connection test
└── nodes/
    └── Renderly/
        ├── Renderly.node.ts              # Main node: Create Render, Get Status, List Projects/Templates
        ├── renderly.svg                  # Node icon
        └── triggers/
            └── RenderlyTrigger.node.ts   # Webhook trigger: Render Completed, Render Failed

Credentials

Type: API Key (Generic Auth)

The credential uses n8n's IAuthenticateGeneric to inject the Authorization: Bearer <key> header on every request. Connection is verified via POST /api/v1/auth/verify.

authenticate: {
  type: 'generic',
  properties: {
    headers: {
      Authorization: '=Bearer {{$credentials.apiKey}}',
    },
  },
};

test: {
  request: {
    baseURL: 'https://renderly.video/api/v1',
    url: '/auth/verify',
    method: 'POST',
  },
};

Nodes

Renderly (Action Node)

Main node with four operations:

Operation	Description
Create Render	Start a video render from a project or system template with dynamic replacements
Get Render Status	Check the status of a render job by ID
List Projects	List user's projects with dynamic overlays
List Templates	List public system templates

Create Render

Flow:

1. User selects "Render From" — My Project or System Template
2. A resourceLocator field appears with a searchable dropdown (powered by listSearch methods)
3. User provides replacements as a JSON object
4. Optional overrides: width, height, fps, durationInFrames, webhookUrl

Key design: Unlike Zapier (which uses replacement_ prefixed dynamic fields) or Make (which sends flat params), n8n uses a single JSON field for replacements. This is simpler and gives users full control via n8n expressions like {{ $json.fieldName }}.

Output: Job ID, status, credits used, render mode.

Get Render Status

Input: Job ID (string)
Output: Job ID, status, progress, output URL, file size, credits used, duration, error message, timestamps.

Renderly Trigger (Webhook Node)

Webhook-based trigger with automatic lifecycle management.

Event	Description
Render Completed	Fires when a video render finishes successfully
Render Failed	Fires when a video render fails

Lifecycle:

• create: When workflow activates, registers a webhook with POST /api/v1/webhooks
• checkExists: Verifies the webhook still exists on Renderly's side via GET /api/v1/webhooks
• delete: When workflow deactivates, removes the webhook via DELETE /api/v1/webhooks?id=X

Payload fields: event, timestamp, jobId, status, outputUrl, errorMessage, creditsUsed, duration, fileSize, completedAt, failedAt.

API Endpoints Used

Endpoint	Method	Used By
/api/v1/auth/verify	POST	Credential test
/api/v1/projects?dynamic=true	GET	listProjects search method
/api/v1/templates	GET	listTemplates search method
/api/v1/renders	POST	Create Render operation
/api/v1/renders/:jobId	GET	Get Render Status operation
/api/v1/webhooks	GET	checkExists webhook lifecycle
/api/v1/webhooks	POST	create webhook lifecycle
/api/v1/webhooks?id=X	DELETE	delete webhook lifecycle

Key Design Decisions

Replacements as JSON (not dynamic fields)

Zapier generates individual fields per dynamic variable (prefixed with replacement_). Make uses flat parameters collected server-side. For n8n, a single JSON field is the best approach because:

1. n8n's expression system ({{ $json.fieldName }}) makes it easy to build JSON from upstream nodes
2. No need for server-side passthrough() or client-side prefix stripping
3. Users can construct the replacements object dynamically with n8n's Function or Set nodes
4. Avoids the complexity of altersDynamicFields (Zapier) or nested RPC (Make)

Resource Locator for Project/Template Selection

n8n's resourceLocator type provides both a searchable dropdown and a manual ID input mode. This is equivalent to:

• Zapier's hidden triggers + dynamic property
• Make's RPCs with store/options

The listSearch methods on the node class power the dropdown data.

Webhook Lifecycle via webhookMethods

n8n manages webhook registration automatically. When a workflow with a Renderly Trigger is activated, n8n calls create() to register the webhook. When deactivated, it calls delete(). This maps directly to Renderly's POST /api/v1/webhooks and DELETE /api/v1/webhooks?id=X endpoints — the same pattern used by Zapier's REST Hooks and Make's Dedicated URL webhooks.

Error Handling with continueOnFail

The main node's execute loop checks this.continueOnFail() — if the user has enabled "Continue on Fail" in n8n, errors are captured and passed downstream instead of stopping the workflow. This is important for batch operations.

Differences from Zapier and Make

Aspect	Zapier	Make	n8n
Config method	CLI + CommonJS	Web UI + JSON	TypeScript npm package
Distribution	Zapier App Directory	Make App Directory	npm registry
Auth mechanism	Custom fields	Connection JSON	IAuthenticateGeneric
Dynamic fields	altersDynamicFields + function	nested RPC on select	JSON field + expressions
Replacement handling	replacement_ prefix, stripped client-side	Flat params, collected server-side	Structured JSON, sent as-is
Webhooks	REST Hook (built into trigger type)	Dedicated URL Address	webhookMethods lifecycle
Dropdown source	Hidden triggers with dynamic	RPCs with store/options	resourceLocator + listSearch
Hosting	SaaS only	SaaS only	Self-hosted or n8n Cloud

Development

Build

cd queue/integrations/n8n
npm install
npm run build

Local Testing with n8n

# Link the package for local development
cd queue/integrations/n8n
npm link

# In your n8n installation directory
npm link n8n-nodes-renderly

# Start n8n — it will pick up the linked package
n8n start

Or use n8n's custom extension directory:

# Set N8N_CUSTOM_EXTENSIONS env var to the dist directory
export N8N_CUSTOM_EXTENSIONS=/path/to/queue/integrations/n8n/dist
n8n start

Publishing

# Build and publish to npm
cd queue/integrations/n8n
npm run build
npm publish

Once published, users install via:

• n8n Cloud: Settings → Community Nodes → Install → n8n-nodes-renderly
• Self-hosted: npm install n8n-nodes-renderly in the n8n installation directory, then restart n8n

No review process required (unlike Zapier/Make app directories). The n8n-community-node-package keyword in package.json makes it discoverable in n8n's community node search.