# Use Narrareach with n8n

The Narrareach-maintained community package `n8n-nodes-narrareach` provides native publishing actions without requiring users to recreate standard calls in an HTTP Request node.

## Install and connect

1. In n8n, open **Settings → Community Nodes**.
2. Install `n8n-nodes-narrareach` and review the community-node notice.
3. In Narrareach, create a scoped automation token under Settings → Integrations → REST API & webhooks.
4. Add a Narrareach API credential in n8n and store the token only in the credential field.
5. With the writer's approval, schedule one future-dated test item, then use **Get Status** to check it. Cancel the test before its publishing time if it should not be published.

## Available actions

- **Schedule Article** — schedule approved long-form content, or an existing Narrareach draft, to supported destinations at one shared time or a different time per platform.
- **Schedule Note** — schedule approved short-form content and supported media, or post it now. Optional fields cover a first reply, per-platform versions, and Instagram accounts with their own captions.
- **Get Status** — inspect a Note, article schedule, or accepted operation.
- **Reschedule** — move an existing queued item using its returned identifier.
- **Cancel** — cancel future publishing without creating a duplicate item. For a Note that may already be published, **Confirm Uncertain Delete** removes only the Narrareach record.
- **List Reader Activities** — read Substack likes, comments, and restacks from Inbox or History, with type, sort, and cursor paging. Requires `activity:read`.
- **Update Reader Activity** — move an item between Inbox and History. Requires `activity:write`.
- **Reply to Reader Activity** — publish a reply to a Substack comment with an idempotency key, then move it to History. Requires `activity:write`.
- **Get Stats Outcomes** — read stored Stats for a preset or custom period, filtered by platform, content type, or publication. Requires `notes:read`.

LinkedIn, Instagram, LinkedIn article, and Medium publication fields offer a list loaded from the connected account; an expression can supply the id instead.

## Start a workflow when a Note publishes or fails

The Narrareach node has no trigger yet. Use n8n's built-in **Webhook** node instead:

1. Add a **Webhook** node with HTTP method `POST` and copy its production URL. Activate the workflow so the production URL accepts requests.
2. In Narrareach, open Settings → Integrations → REST API & webhooks, paste the URL under Webhooks, and choose **Add webhook**. Copy the signing secret now; it is shown once.
3. Choose **Test** to send a `webhook.test` event and confirm the workflow receives it.
4. Branch on `body.event` with an **If** or **Switch** node, then use `body.data.note.id` with **Get Status** when you need the latest state.

### Webhook events

- `note.published` — a Note was published. `data.note.postUrl` holds the platform URL when the platform returns one.
- `note.failed` — a Note could not be published. `data.note.error` holds the reason.
- `webhook.test` — sent only by **Test**.

Scheduled Notes send events for Substack, LinkedIn, X, Threads, Instagram, Facebook, TikTok, and Pinterest. Notes posted right away through `POST /api/v1/notes` send events for every platform. Articles do not send webhook events yet, and scheduled Bluesky Notes may not send them; use the status endpoints for those.

Each Note platform sends its own event. The JSON body looks like this:

```json
{
  "id": "stable event id",
  "event": "note.published",
  "createdAt": "2026-10-07T13:00:05.000Z",
  "data": {
    "note": {
      "id": "note id",
      "draftId": null,
      "platform": "SUBSTACK",
      "content": "Note text",
      "status": "POSTED",
      "scheduledFor": "2026-10-07T13:00:00.000Z",
      "postedAt": "2026-10-07T13:00:04.000Z",
      "postUrl": "https://...",
      "externalPostId": "platform post id",
      "imageUrls": [],
      "attachments": [],
      "error": null
    },
    "source": { "product": "narrareach" }
  }
}
```

### Verify and handle deliveries

- Headers: `X-Narrareach-Event`, `X-Narrareach-Delivery`, `X-Narrareach-Timestamp`, and `X-Narrareach-Signature` in the form `t=TIMESTAMP,v1=SIGNATURE`.
- To verify, compute an HMAC-SHA256 hex digest of `TIMESTAMP.RAW_BODY` using the signing secret and compare it with `v1`. Use the raw request body, not re-serialized JSON, and reject old timestamps.
- Respond with any 2xx status within 8 seconds. Other responses and timeouts are retried with increasing delays, up to 5 attempts in total.
- The same event can arrive more than once. Use the body's `id` to ignore duplicates.
- Deliveries are sent within about a minute of the event.


## Recommended workflow

`Source trigger → transform → approval → Narrareach action → persist ID → Get Status → branch on state`

Use an immutable source-record identifier as the idempotency key. Keep n8n responsible for triggers and branching while Narrareach remains responsible for connected destinations and publishing state.

## Safe retry pattern

- Reuse the source-record idempotency key for retries.
- Run **Get Status** when you have a returned id. Choose Note, Article Schedule, or Operation to match that id. An article response's draftId is not its schedule id: use the id in scheduled[].
- If a timeout returned no id, retry the identical create request with the same idempotency key. Do not generate a new key for that retry.
- Branch authorization failures to credential review.
- Branch validation failures to human review.
- Do not store platform passwords or session material in the workflow.

The node uses the account that created its automation token. Team workspace selectors are not currently exposed by the node; do not assume the MCP team selection fields are available here.

- Package: https://www.npmjs.com/package/n8n-nodes-narrareach
- Source and starter workflows: https://github.com/iancarson/Scribe-sync/tree/master/integrations/n8n-nodes-narrareach
- Complete Narrareach documentation: https://www.narrareach.com/api-docs.md