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.

Table of Contents

• Installation
• Credentials
• SmartProof (Action Node)
  • Client
  • Location
  • Review
  • Tag
  • Widget
  • IDs and External Refs
  • Get Many: Return All & Filters
  • Include Link to Workflow
• SmartProof Trigger
  • Webhook Registration
  • Signature Verification
  • Event Payloads
• Idempotent Review Ingest
• Compatibility
• License

Installation

Community Node (Recommended)

1. In your n8n instance, go to Settings > Community Nodes
2. Select Install
3. Enter @belmontdigitalmarketing/n8n-nodes-smartproof
4. 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.

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 to verify event signatures (when Verify Signature is on).

The trigger uses both credentials: SmartProof API (to self-register its webhook with SmartProof on activation) and SmartProof Webhook API (to verify the HMAC on each delivery).

SmartProof (Action Node)

Choose a Resource, then an Operation.

Client

Location

Review

The workhorse resource.

Create / Ingest top-level fields: Location, Source, Source Native ID, Text, Author Name (all required), plus Rating and Review Date (commonly used, so surfaced directly). The rest live under Additional Fields (Source URL, Title, Author Avatar URL, Author Tagline, Tags, Include Link to Workflow).

Featured is intentionally not a Create field — the API doesn't accept it on ingest. Reviews arrive as pending/not-featured; you mark one featured via the Update operation, and that flag is preserved across re-ingests.

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

Tags are global — shared across all clients (no per-client scoping). label is globally unique; an optional category groups them by industry.

Attaching tags to a review is separate from this resource — pass labels in the Review Tags field (Create/Update); unknown labels auto-create a global tag.

Widget

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.

When filtering or scoping by Client on a Get Many, the field is a name dropdown populated live from your account — no need to know the cl_… ID. To filter by a Keap external_ref instead, switch the field to an expression and pass the ref. (Create/Update still take a free-text "Client (ID or External Ref)" so external-ref-driven automations work without expressions.)

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 (automatic)

Registration is automatic. When you activate the workflow, the trigger registers its production webhook URL with SmartProof (via POST /event-subscriptions, using your API key) for exactly the events you selected; when you deactivate, it removes the subscription. No manual URL copying needed — just set both credentials and pick your events.

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

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