n8n node

The CastPDF community node for n8n lets a workflow create PDFs from your CastPDF templates or from HTML, read your templates, and start when a PDF is ready or has failed. It is the package @castpdf/n8n-nodes-castpdf on npm, and it contains two nodes: CastPDF for actions and CastPDF Trigger for events. Use it when you build workflows in n8n and want template fields to map without writing JSON by hand.

Install

Install the package as a community node, following n8n's installation guide for community nodes. The package name to enter is:

@castpdf/n8n-nodes-castpdf

The node is built for n8n 2.x: the template fields use n8n's resource mapper and the trigger uses webhooks, so use a current n8n version. The trigger also needs an n8n instance that CastPDF can reach over public https (below).

Credentials

The nodes authenticate with a CastPDF API key.

1. Sign up at castpdf.com if you have no account yet.
2. In the CastPDF dashboard, open Connect, then API, and create an API key.
3. In n8n, create a CastPDF API credential and paste the key into API Key. Leave Base URL as it is (https://api.castpdf.com).

n8n checks the key when you save the credential, with a call to GET /v1/me. The key decides the mode: a live key (cpdf_live_) makes real PDFs that count toward your plan, and a test key (cpdf_test_) makes free PDFs with a "CASTPDF TEST" watermark. See test and live mode.

Operations

Both PDF operations call POST /v1/pdf and return the PDF's details: id, status, download_url (a signed link), expires_at, pages, size (bytes), test, filename and warnings (the number of warnings). Turn on Download PDF File to also get the PDF itself as binary data, in the field named under Put Output File in Field (data by default), ready for an email or file storage node.

Create From Template

1. Pick the Template from the searchable list, or paste its ID.
2. Under Data, choose Template Fields. The template's fields appear, read from its sample data: one field per value (such as Customer > Name) and one list field per group of line items. Map a list of objects to a line item field, for example {{ $json.line_items }}.
3. Numbers and true or false values are converted to the type the template expects, so text such as 1,234.50 works.
4. Fields you leave empty are left out. If you fill in nothing at all, CastPDF renders the template with its sample data, which is handy for a first test.

With Map Automatically, every field of the input item is sent to the template, and fields the template does not use are ignored. A template without sample data has no fields to list: add sample data to it in CastPDF and reload the fields, or set Data to JSON and give the whole data object. The File Name option sets the PDF's name (up to 100 characters).

Create From HTML

Type or map the page as HTML, up to 5 MB. Images and fonts must be on public web addresses (images and fonts). The options are CSS (styles added to the page), File Name, Orientation (portrait or landscape), Page Size (A4, A5, US Letter or US Legal) and Render Mode: Fast (the default for HTML) or Print, for precise page breaks, running headers and page numbers (fast and print mode).

Template Get and Get Many

Get returns one template with its HTML, CSS and sample data; the Version option gets an older version instead of the current one. Get Many lists your templates, most recently changed first: up to Limit (50 by default), or all of them with Return All.

Test mode

Turn on Test Mode on a PDF operation while you build the workflow. It sends "test": true, so even with a live key the node makes a free, watermarked test PDF that does not count toward your plan. Turn it off when the workflow goes live. With a test key, every PDF is a test PDF whatever the switch says.

The trigger

CastPDF Trigger starts the workflow when a PDF is ready (pdf.created), when a PDF failed (pdf.failed), or both. It fires for PDFs from any source: the API, a batch, a spreadsheet run or another workflow. Set Template to start only for PDFs made from one template.

The webhook endpoint it creates

Activating the workflow creates a CastPDF webhook endpoint that points at the trigger's n8n URL, in the mode of the credential's key. Its description starts with n8n: (such as n8n: PDF ready (workflow 12)), so you can tell it apart in the dashboard under Connect, then Webhooks. Deactivating the workflow deletes it. If you change the events, or the endpoint was disabled or deleted in the dashboard, the node replaces it the next time the workflow is activated.

The node keeps the endpoint's signing secret and checks every incoming request against the CastPDF-Signature header. A request without a valid signature from the last 5 minutes is answered with 401 and starts nothing (verifying the signature).

Each event starts the workflow with one item that holds the document's id, status, download_url, expires_at, pages, size, test, filename, template_id, template_version, batch_id, metadata, error_code and error_message, plus the event's event_id, event_type, livemode and test_event.

Modes

A live key hears about live PDFs, and a test key about test PDFs. So PDFs made with Test Mode on do not start a workflow whose trigger uses a live key. Use a test key in the trigger's credential while you build, and switch it to a live key when you go live.

Limits

• Webhooks need a paid plan. The trigger is included in the Starter, Growth, Pro and Scale plans. On the Free plan, activating the workflow shows an error (feature_not_available) that says so. The CastPDF node itself works on every plan.
• Endpoints. Each active trigger uses one of the team's 10 webhook endpoints (live and test together).
• Public https only. CastPDF sends webhooks only to public https addresses, so an n8n running on localhost cannot receive events. Use n8n Cloud, a server with a public https address, or a tunnel.
• Rate limits. The node's requests count like any other API request: 20 a minute for test keys, and your plan's limit for live keys. On a 429, turn on Retry On Fail in the node's settings (rate limits).
• Plan usage. Every live PDF the node makes counts toward your plan like any other document (usage and billing).

Next steps

• Integrations: every way to connect CastPDF.
• Templates: design the template the node fills.
• Webhooks: the events the trigger receives.
• Troubleshooting: fixes for common errors.