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.

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

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

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

| Operation | Description | |-----------|-------------| | Create | POST /clients — Name (required); optional Slug, Website, External Ref, Status. Primary Location: fill it in to create the client's first location in the same call, leave it empty to auto-create a default location (named after the client), or turn off Create Default Location for none. The created location is returned on the response. | | 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 Image | GET /reviews/{id}/image.png — returns the review social card as a PNG binary property (Theme, Accent, Width, Height options). Use it to attach/post a social graphic. | | Get Many | GET /reviews — filters: Client, Location, Source, Status, Featured, Min/Max 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 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.

| Operation | Description | |-----------|-------------| | Create | POST /tags — Label (required) + optional Category. Idempotent: an existing label returns the existing tag | | Get Many | GET /tags — all global tags (no pagination); optional Category filter | | Delete | DELETE /tags/{id} (uses the tag_… ID) |

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

| 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.

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

| 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