> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nephia.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# n8n

> The official Nephia nodes for n8n — a trigger that turns a watch into a workflow, and an action node covering every pull endpoint.

`n8n-nodes-nephia` ships two nodes:

* **Nephia Trigger** — creates a watch when you activate the workflow, deletes it when you deactivate it, and starts a run on every event.
* **Nephia** — every documented `/v1` pull operation, with the credit cost shown on each one.

Both are generated from the same OpenAPI spec as the [SDKs](/sdk), so a new
source or parameter appears in the node's dropdowns rather than in a changelog.

## Install

In your n8n instance: **Settings → Community nodes → Install**, then enter:

```
n8n-nodes-nephia
```

Self-hosted instances need `N8N_COMMUNITY_PACKAGES_ENABLED=true` (the default).

## Credential

Add a **Nephia API** credential:

| Field                  | Notes                                                             |
| ---------------------- | ----------------------------------------------------------------- |
| API Key                | From the dashboard's API Keys page. Sent as `x-api-key`.          |
| Base URL               | `https://api.nephia.cc`. Only change it for a proxy.              |
| Webhook Signing Secret | Optional — see [Signature verification](#signature-verification). |

**Test** calls `GET /v1/account/credits`, which is free.

## Nephia Trigger

Pick a **Source**, describe what to watch, and set a refresh interval — the
floor differs per source and the field enforces it ([Watches](/watches)).

The node owns the watch's whole life: activating the workflow creates it,
deactivating deletes it, and the watch id is kept in the workflow's static
data. Do not also create the watch by hand — you would pay for two.

### Webhook mode (default)

The watch is created with `webhook_url` pointing at this node's n8n webhook
URL. Nephia POSTs each event, n8n answers `200` immediately, and the workflow
runs after. One event, one item, in the [envelope](/webhooks#payload-envelope)
the API documents.

Needs an n8n instance reachable from the internet.

### Poll mode

For instances behind a firewall. The watch is created *without* a
`webhook_url`, and n8n asks for new events on its own schedule using the free
[replay endpoint](/webhooks#replay-events). Nothing has to reach your network.

The trade-off is latency: you see an event on the next poll, not the second it
happens.

### Signature verification

Each delivery carries `X-Signature` ([how it is built](/webhooks#signature-verification)).
Paste your signing secret into the credential and the trigger verifies every
delivery against the raw body, rejecting anything that fails with `401`.

Leave it empty and the trigger accepts any POST to its URL. That URL is
unguessable, which is the same protection any n8n webhook has — but if the
event will drive something that matters, set the secret.

### Duplicates

Nephia retries a failed delivery at +0s, +30s and +120s, and n8n retries a
failed execution on its own terms. The trigger remembers the `event.id`s it
has seen for 24 hours and drops the repeats, but that is best-effort: if
running twice would be expensive, stay idempotent on `event.id` downstream.

### When a watch is paused

A paused watch — out of credits, too many delivery failures, paused by
support — looks exactly like a quiet one. Both modes re-read the watch once an
hour and emit a distinct item when the reason changes:

```json theme={null}
{
  "type": "watch.paused",
  "watchId": "watch_01k2xyz",
  "pausedReason": "insufficient_credits",
  "isActive": false,
  "occurredAt": "2026-08-26T09:00:00.000Z"
}
```

Branch on `type` to alert yourself. `pausedReason` says what unblocks it — see
[Pause reasons](/watches#pause-reasons).

<Note>
  In **Webhook** mode the built-in **Poll Times** field is used only for this
  hourly check; events still arrive over HTTP.
</Note>

## Nephia (action node)

Pick a **Resource** and an **Operation**. The operation dropdown shows the
credit cost from the spec, so you can price a run before making it.

* **Required fields** sit at the top level; everything else is under
  **Additional Fields**.
* **Return All** follows pagination — cursor, page + per page, or page,
  whichever the operation speaks — up to **Max Pages** (default 5). Every page
  costs credits; the node logs a warning when the cap stopped it early.
* **Split Into Items** (on by default) emits one item per result. Turn it off
  to get the raw response, cursor included, as a single item.
* POSTs carry an `idempotency-key` that is reused across retries, so a retried
  create never makes a second watch.
* `429` and upstream `503 RATE_LIMITED` are retried with `Retry-After`;
  `402` says to top up rather than to try again ([Errors](/errors)).

The **Watches** resource covers all eight watch routes for all seven sources —
useful for listing, pausing, resuming, or replaying events from a workflow
that did not create the watch.

## Templates

Six starting points ship with the package under `templates/`, and are
published on n8n.io:

| Template                                 | What it does                                          |
| ---------------------------------------- | ----------------------------------------------------- |
| Vinted price drop → Discord              | Filters `listing.price_changed` down to actual drops. |
| Reddit mention → Slack, classified       | Classifies the post, then posts the verdict.          |
| Hacker News mention → Notion             | Rows with points, author and the discussion link.     |
| YouTube new video → transcript → summary | Pulls the transcript, summarises, emails it.          |
| Backfill an X search → Google Sheets     | One-off, **Return All**, capped.                      |
| Daily digest of a watch → email          | Free replay of the last 24 hours.                     |

## Limits

* One watch per node. Several watches means several trigger nodes, and your
  plan's watch cap applies ([Limits](/limits)).
* The action node's AI resource is not included; run an
  [agent step](/ai) on the watch instead, and read it from `event.ai`.
* Copying a workflow to another instance re-creates the watch on first
  activation, because the old one points at the old URL.