Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@belmontdigitalmarketing/n8n-nodes-smartproof) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

n8n-nodes-smartproof

An n8n community node package for SmartProof — review ingest, moderation, tags, and widget management, plus a trigger that receives SmartProof's signed outbound events.

This package contains:

SmartProof (action node) — drive the SmartProof Automation API: Clients, Locations, Reviews, Tags, and Widgets.
SmartProof Trigger (webhook node) — start a workflow on review.created, review.updated, and review.negative events, with HMAC signature verification.

Installation
Credentials
SmartProof (Action Node)
SmartProof Trigger
Idempotent Review Ingest
Compatibility
License

Installation

Community Node (Recommended)

In your n8n instance, go to Settings > Community Nodes
Select Install
Enter @belmontdigitalmarketing/n8n-nodes-smartproof
Agree to the risks and click Install

Manual Installation

For self-hosted n8n instances:

cd ~/.n8n/custom
npm install @belmontdigitalmarketing/n8n-nodes-smartproof

Then restart n8n.

Credentials

This package uses two credential types so a trigger-only workflow never has to hold an API key it doesn't need.

SmartProof API

Used by the action node.

Field	Required	Description
Base URL	Yes	Base URL of the API including `/api/v1`. Default `https://smartproof.pro/api/v1`. Point at `http://localhost:8787/api/v1` for local dev.
API Key	Yes	Sent as `Authorization: Bearer <api_key>` on every request.

Click Test to verify — it calls GET /clients?limit=1, so a 200 confirms the key and base URL.

SmartProof Webhook API

Used by the trigger node (only when Verify Signature is on).

Field	Required	Description
Signing Secret	Yes	The shared HMAC secret configured on the SmartProof side (`EVENT_SIGNING_SECRET`).

SmartProof (Action Node)

Choose a Resource, then an Operation.

Client

Operation	Description
Create	`POST /clients` — Name (required); optional Slug, Website, External Ref, Status
Get	`GET /clients/{idOrRef}`
Get Many	`GET /clients` — Return All / Limit; optional External Ref exact lookup
Update	`PATCH /clients/{idOrRef}`
Delete	`DELETE /clients/{idOrRef}` — cascades to locations, reviews, tags, widgets

Location

Operation	Description
Create	`POST /locations` — Client (required) + Label (required); optional Google Place ID, Address, External Ref
Get	`GET /locations/{idOrRef}`
Get Many	`GET /locations` — filter by Client; Return All / Limit; External Ref exact lookup
Update	`PATCH /locations/{idOrRef}`
Delete	`DELETE /locations/{idOrRef}` — cascades to its reviews

Review

The workhorse resource.

Operation	Description
Create or Ingest	`POST /reviews` — idempotent upsert (see below)
Get	`GET /reviews/{id}` (uses the `rev_…` ID)
Get Many	`GET /reviews` — filters: Client, Location, Source, Status, Featured, Min Rating, Tag, Sort
Update	`PATCH /reviews/{id}` — Text, Title, Rating, Status, Featured, Reply Status, Author Name/Tagline, Review Date, Tags
Delete	`DELETE /reviews/{id}`

Create / Ingest required fields: Location, Source, Source Native ID, Text, Author Name. Everything else lives under Additional Fields (Rating, Title, Source URL, Author Avatar URL, Author Tagline, Review Date, Tags).

Reviews have no external ref — Get / Update / Delete use the SmartProof rev_… ID. To find a review by its source ID, use Get Many with a Source filter and match source_native_id.

Tag

Operation	Description
Create	`POST /tags` — Client + Label. Idempotent: an existing `(client, label)` returns the existing tag
Get Many	`GET /tags?client_id=` — requires a Client; returns all tags (no pagination)
Delete	`DELETE /tags/{id}` (uses the `tag_…` ID)

Operation	Description
Create	`POST /widgets` — Client + Name; optional Location, Style, Tag Filter, Config (JSON)
Get	`GET /widgets/{id}` (uses the `wid_…` ID)
Get Many	`GET /widgets?client_id=` — requires a Client; Return All / Limit
Update	`PATCH /widgets/{id}` — add Location and leave it empty to clear it (show on all locations)
Delete	`DELETE /widgets/{id}`

IDs and External Refs

Anywhere a client or location is referenced, you can pass either the SmartProof ID (cl_…, loc_…) or an external_ref you set on creation (e.g. a Keap ID). These fields are labelled "… (ID or External Ref)". Reviews, tags, and widgets are addressed by their SmartProof IDs only.

Get Many: Return All & Filters

For Client, Location, Review, and Widget, Get Many offers a Return All toggle. When off, set a Limit. When on, the node walks offset (page size 100) until the list is exhausted. Filters are added under the Filters collection per resource.

Include Link to Workflow

Review Create or Ingest and Update offer an Include Link to Workflow toggle (default off). When enabled, the node adds a workflowLink property to its output — handy for downstream Slack/email steps (e.g. a bad-review alert that links back to the workflow). It deliberately does not write into the review text, so published, public-facing testimonials stay clean.

SmartProof Trigger

Listens for SmartProof's outbound events and emits each payload as an item ({ event, data, sent_at }).

Webhook Registration

Self-registration is not available yet (SmartProof roadmap Phase 5), so registration is manual:

Add a SmartProof Trigger node and open it.
Copy the Production webhook URL.
In SmartProof, register that URL plus the shared signing secret on the SmartProof side.

SmartProof will then POST events to the URL. When the event-subscriptions endpoint ships, this node can be upgraded to self-register on activation.

Signature Verification

With Verify Signature on (default), the node computes HMAC-SHA256(signingSecret, rawBody) as lowercase hex and compares it (timing-safe) against the x-smartproof-signature header. A mismatch — or a missing secret/signature — is rejected with HTTP 401 and nothing is emitted.

Verification hashes the raw request bytes. This relies on n8n exposing the raw body to the webhook (the standard behaviour in supported n8n versions). If you proxy webhooks through middleware that rewrites the body, the signature may not match.

Event Payloads

Event	`data` shape
`review.created`	the review object
`review.negative`	the review object (fires alongside `review.created` when rating ≤ 3)
`review.updated`	`{ old, new }` — both full review objects

Use the Events multi-select to subscribe to a subset; unselected events are acknowledged with 200 but do not start the workflow.

Idempotent Review Ingest

POST /reviews upserts on (location_id, source, source_native_id):

First call → creates the review (HTTP 201), status defaults to pending, fires review.created (and review.negative if rating ≤ 3).
Same triple again → updates in place (HTTP 200), no duplicate, re-applies provided fields, preserves operator-owned status and featured, fires review.updated.

This makes the Ingest operation safe to re-run for backfills and syncs. client_id is derived from the location — you don't send it.

Compatibility

n8n: 1.x
Node.js: 18.10 or later

License

MIT

@belmontdigitalmarketing/n8n-nodes-smartproof