Package Information
Documentation
@shakewell/n8n-nodes-shakewell-wallet
n8n community nodes for Shakewell Wallet: act on members, passes, stamps, points and rewards, and start workflows from loyalty events.
The nodes call the same Open API as the Shakewell Zapier app (/api/open/v1).
Install
In n8n: Settings > Community Nodes > Install, enter @shakewell/n8n-nodes-shakewell-wallet.
Self-hosted without the UI: npm install @shakewell/n8n-nodes-shakewell-wallet in ~/.n8n/nodes, then restart n8n.
The package is not on npm yet (the publish step is a separate launch ticket). Until then, build it and install the tarball:
npm ci && npm run build && npm pack
# in your n8n custom folder, e.g. ~/.n8n/custom/shakewell:
tar xzf shakewell-n8n-nodes-shakewell-wallet-0.1.0.tgz --strip-components=1
# set N8N_CUSTOM_EXTENSIONS=~/.n8n/custom and make n8n-workflow resolvable from that folder
Credentials
Shakewell Wallet API
| Field | Value |
|---|---|
| API Key | A key from the Shakewell admin, Settings > API keys. Use a key with the write scope: the trigger creates a webhook subscription and actions change data. |
| Base URL | https://api.shakewellwallet.com (default). https://wallet.shakewell.net for staging. |
The key is sent in the X-API-Key header. The credential Test button calls GET /auth, which returns the account.
OAuth2 is not offered: the Shakewell API authenticates iPaaS integrations with API keys only.
Shakewell Wallet node
| Resource | Operations | Endpoint |
|---|---|---|
| Member | Create | POST /members |
| Member | Find (by email or phone, exact match) | GET /members |
| Member | Send Pass Notification | POST /members/{id}/notifications |
| Pass | Find (by member email or barcode value) | GET /passes |
| Pass | Get | GET /passes/{id} |
| Stamp | Add | PATCH /passes/{id}/add-stamps |
| Point | Adjust (with reason) | POST /members/{id}/points |
| Reward | Issue (from a reward template) | POST /members/{id}/rewards |
Each operation returns the endpoint's data object (Find operations return one item per match).
Every write operation has an Idempotency Key that is sent as the Idempotency-Key header. Shakewell applies a key once for 24 hours, so a retried run cannot apply twice. It is required for Point > Adjust and Reward > Issue: map a unique id such as the trigger's event_id. For Stamp > Add it is optional: map the event_id (or another unique value) to make retries safe. A blank key is not sent, and with Stamp > Add that means a retry can add the stamps twice, so turn off Retry On Fail on that node.
Member > Find, Member > Create and Pass > Find fail with a clear error when none of their lookup fields is filled in.
Shakewell Wallet Trigger
Starts a workflow when the selected events happen. Activating the workflow subscribes the workflow's webhook URL (POST /webhooks); deactivating deletes the subscription. Every delivery is verified with X-Shakewell-Timestamp and X-Shakewell-Hmac-Sha256 (HMAC-SHA256 over {timestamp}.{raw body}, 5 minute tolerance) using the secret returned at subscribe time. A delivery that fails verification gets a 401 and does not start the workflow.
The webhook URL must be reachable from the internet over HTTPS: Shakewell refuses private and loopback addresses. Self-hosted instances need WEBHOOK_URL set to their public address.
Events: Member Enrolled, Pass Installed, Pass Removed, Points Earned, Points Expired, Points Redeemed, Reward Earned, Reward Redeemed, Stamp Card Completed, Stamp Earned, Tier Changed (tier.upgraded and tier.downgraded). Each item is the event envelope: event_id, type, occurred_at, account_id, member, data, source. Delivery is at least once, so dedupe on event_id. Stamp Earned is recorded for stamp rows and POS stamp events; PATCH /passes/{id}/add-stamps only increments the pass counter and emits no event.
Not included
These appear in the planning tickets but the Open API has no endpoint or event for them, so they are left out rather than invented:
- Member > Update, Pass > Send Install Link (the install links are returned by Member > Create), Tier > Change and Reward > Mark Redeemed. Member > Get by phone is covered by Member > Find.
- OAuth2 credentials.
API keys with the Zapier-only scope are restricted to the Zapier route allow-list, so they cannot call Pass > Get, and they are not meant for n8n. Use a general read and write key.
Development
npm ci
npm run lint
npm test # builds, then runs the unit tests (signature verification, request mapping)
npm run dev # n8n with hot reload (n8n-node dev)
CI runs lint, build and tests on every pull request. .github/workflows/publish.yml publishes on a version tag but is disabled (if: false) until the npm scope and a trusted publisher or NPM_TOKEN secret exist.