Postial for n8n

Community nodes for Postial, formerly published as SocialMint, by productivity-boost.com Betriebs UG. Create social posts and receive publishing and approval events in n8n.

Version 0.2.1. MIT licensed. Install the renamed package n8n-nodes-postial.

Installation

Open Settings → Community Nodes → Install in your self-hosted n8n instance and enter n8n-nodes-postial. Confirm installation, then search for Postial or Postial Trigger in the node picker. n8n Cloud discovery requires approval through n8n's community package verification process.

For local development, run npm ci, npm run build, and npm run dev in this repository. The official n8n node CLI provides the local development environment.

Credentials

Create an API key in Postial under Settings → API using an Agency workspace. Create Postial API credentials in n8n:

• Base URL: https://postial.co (or your Postial installation, without /api/v1).
• API Key: your key. The credential test calls GET /api/v1/me with Bearer authentication.
• Grant brands:read for dropdowns and brand/channel lists, posts:read for post reads, and posts:write for mutations. Automatic webhook registration also needs webhooks:manage.

Never include API keys in workflow examples. Credentials are stored by n8n's credential system.

First workflow

1. In Postial, use an active Agency plan or Agency trial. Create a brand, then open Brands → your brand → Connect a channel and connect at least one publishing account.
2. Under Settings → API, create a key with posts:write, brands:read, and webhooks:manage. Add posts:read if you will retrieve posts. Save it in n8n's Postial API credentials.
3. Create a workflow with Manual Trigger → Postial. Select Post / Create, your brand and connected channel, enter text, and leave Draft selected. Execute it and verify the returned post ID and the draft in Postial.
4. Create a second workflow with Postial Trigger, Automatic registration and Approval Decided. Select credentials and activate the workflow; its production webhook URL must be publicly reachable over HTTPS.
5. In the first workflow, enable Requires Approval, select Scheduled Time, and choose a future date. Execute it, open the returned approval_url, and request changes. The active second workflow receives approval.decided; inspect its execution output. Requesting changes keeps this test post from publishing. Remove the test post in Postial afterward.

Postial's webhook Test button sends ping. The trigger acknowledges it with HTTP 200 but deliberately emits no workflow item; use an approval decision to test visible output.

Troubleshooting

• 401: Check the Base URL and API key, and replace revoked keys. For trigger signature failures, check the signing secret and synchronize host clocks.
• 403: Confirm an active Agency entitlement and the required scopes. Existing keys do not gain scopes automatically; create a replacement key with the needed scopes.
• 422: Read the API validation message. Check brand/channel ownership, HTTPS media URLs (at most four), schedule and text constraints. Webhooks require public HTTPS; the workspace limit is ten endpoints, including inactive ones.
• 429: The API allows 60 requests per minute per key. Respect Retry-After, reduce batch size or add a Wait node before retrying. The node does not automatically retry 429 responses. Preserve the custom key for retries across executions if duplicate creation must be prevented.

Postial node

| Resource | Operations | | --- | --- | | Post | Create, Get, Get Many, Retry, Delete | | Brand | Get Many | | Channel | Get Many by brand |

Create accepts a brand, multiple channels, text, up to four media URLs (one per line), an optional link, draft/now/scheduled time, and an approval flag. Brand and channel dropdowns load from your workspace; expressions can supply IDs. Dates are sent as ISO timestamps. Draft is the safe default.

An automatic Idempotency-Key is SHA-256 over the workflow ID, execution ID, node ID, item index, run index (when supplied by n8n), and a canonical SHA-256 hash of the request body. Identical retries in the same run reuse the key; changed bodies and later runs receive different keys. Custom Idempotency Key accepts an expression to override this behavior, including across executions. Reuse a custom key only for identical requests; changed bodies with that key return 409. The API retains keys for 24 hours.

Get Many supports brand/status filters and Return All or Limit; post pagination follows next_cursor. Outputs are individual items with paired input references. Get returns post targets, publishing events, and approvals. Delete returns { "success": true }; Postial only permits deletion of drafts or unstarted scheduled posts. Retry asks Postial to retry eligible targets and can fail if none are eligible.

API error messages appear in node errors. Use n8n's On Error → Continue (using regular output) to receive { "error": "..." } per failed item and continue processing.

Example: Schedule Trigger → Postial (Post / Create). Select the brand and channels, enter Weekly update, choose Scheduled Time, and set a future date. Enable Requires Approval when review is needed.

After importing examples/create-scheduled-post.json, assign a Postial API credential to its Postial node before running the workflow.

The execution method uses n8n's authenticated HTTP helper for all network requests. Programmatic execution keeps pagination, input pairing, and per-item idempotency consistent across operations; credential authentication and testing use n8n's declarative definitions. There are no external runtime dependencies or runtime file/environment access.

Postial Trigger

Choose one or more events: post.published, post.failed, post.needs_review, approval.decided.

Automatic: activation registers the n8n webhook URL through POST /api/v1/webhooks with {url, events}. The returned endpoint ID and one-time secret are saved in node-scoped workflow static data. Existence checks use GET /api/v1/webhooks, matching the saved ID or the exact webhook URL. Active matching registrations with a known secret are reused. Inactive registrations, changed URL/events, and lost secrets are replaced with DELETE followed by POST because the API does not support PATCH. A failed DELETE preserves recovery state and stops replacement; 404 is harmless. Multiple URL matches require removing duplicates in Postial. Use a dedicated URL per trigger. Deactivation uses DELETE /api/v1/webhooks/{id}. n8n must expose a public HTTPS webhook URL. Automatic mode requires a Postial version with webhook management API routes.

Manual (Paste Secret): register the displayed production webhook URL in Postial yourself and paste its signing secret into the node. No API credentials or management API are required. Deactivation does not remove manually managed endpoints; disable them in Postial yourself. For a manual test, register the test URL and use the matching secret while n8n is listening.

The node checks X-Postial-Signature: t=<seconds>,v1=<hex> using HMAC-SHA256 over the timestamp, a dot, and the original request bytes. It also accepts X-SocialMint-Signature as a compatibility fallback. It compares signatures in constant time and accepts timestamps within five minutes in either direction. Invalid signatures receive HTTP 401, valid selected events receive HTTP 200 and emit the event object. Valid unselected events are acknowledged without starting downstream work. Keep host clocks synchronized.

Delivery is at least once: deduplicate using the event id when downstream actions must happen only once. The five-minute check limits replay age, not repeated deliveries inside that window.

The automatic signing secret is in workflow static data; the manual secret is a password-masked node parameter. These are not n8n encrypted credentials. Restrict workflow/database/export access and remove secrets and static data before sharing exports.

Import examples/approval-to-slack.json, assign a Postial API credential to its Postial Trigger and a Slack credential to its Slack node, replace the Slack channel ID, then activate it. It sends the approval decision and post link to Slack. To send email instead, replace the Slack node with n8n's Send Email node and use $json.data.decision and $json.data.post_url.

Validation

npm ci
npm run lint
npm run build
npm test
npm pack --dry-run

The current official starter's n8n-node lint enables eslint-plugin-n8n-nodes-base plus the community/cloud rules. The strict default ESLint configuration is unchanged; the integration fixture is a template loaded only by the development runner. Unit tests exercise the compiled node and trigger with helper contexts; they need no running n8n server.

The smoke test needs a sibling SocialMint checkout with dependencies installed, a disposable local database, and a built SocialMint server. It creates an Agency fixture, makes real HTTP requests, verifies an actual outbox event over loopback, and removes the fixture in finally. It never publishes a social post or prints credentials.

Start SocialMint in a separate terminal (paths below match the maintainer workspace):

cd /home/flori/ventures2/socialmint/repo
set -a
source /home/flori/ventures2/socialmint/.secrets.env
export DATABASE_URL="${DATABASE_URL_LOCAL}?sslmode=require"
export AUTH_URL=http://localhost:3999 AUTH_TRUST_HOST=true
export NEXT_PUBLIC_APP_URL=http://localhost:3999 PORT=3999 HOSTNAME=127.0.0.1
set +a
npm run build && npm start

In this package's directory, load the same environment, then run npm run smoke. Set SOCIALMINT_REPO or API_HTTP_URL to override the sibling checkout and http://127.0.0.1:3999 defaults. Stop the server after the test.

Production deliberately rejects loopback webhook destinations. The smoke runner therefore uses SocialMint's existing development-only WEBHOOK_ALLOW_LOOPBACK=1 support in a separate process for dispatch and webhook management route tests, while post CRUD targets the built server. It does not weaken production URL validation. When webhook management routes are absent, the test uses the real service functions and explicitly prints OPEN; rerun after those routes land to complete HTTP management verification.

Release

Trusted Publishing is configured for this repository. After checks, push the matching version tag (git tag v$(node -p "require('./package.json').version") followed by git push origin v$(node -p "require('./package.json').version")). The Publish GitHub Action runs npm ci, lint, build, and tests, then npm publish --provenance --access public using GitHub OIDC. Tags must match the package version. Do not publish from a local shell.

Before tagging, run all validation commands and the local smoke test, inspect npm pack --dry-run, and perform an n8n editor activation/deactivation test. After publication, verify npm provenance, run npx @n8n/scan-community-package n8n-nodes-postial, and submit for n8n verification.

References checked September 9, 2026: official starter, verification guidelines, Postial API documentation. The guidelines require GitHub Actions publication with provenance, MIT licensing, English documentation, and no external runtime dependencies or file/environment access.