swum

Swum swim-school actions and signed event triggers for n8n

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.2.0
Author: Swum

Documentation

n8n-nodes-swum

Swum nodes for n8n. Swum is scheduling, CRM and payments software for swim schools.

This package has two nodes:

  • Swum: add families and swimmers, request enrollments, mark attendance and send messages.
  • Swum Trigger: start a workflow when something happens in your school, such as a new client, a booking or a failed payment.

Both nodes act through a dedicated Swum app key. The key's school, permissions and allowed pools decide what a workflow can see and change.

Installation · Credentials · Swum node · Swum Trigger · Example workflows · Compatibility

Installation

n8n Cloud: open the nodes panel, search for Swum, and add it. (Available once n8n has verified the package.)

Self-hosted n8n: go to Settings > Community Nodes > Install, enter n8n-nodes-swum, and install. See n8n's community nodes installation guide.

Credentials

You need a Swum school on a plan that includes the API, and a dedicated n8n key.

  1. In Swum, open Developers & Integrations > Apps > n8n and create an n8n key. Review its permissions and allowed pools before you save.
  2. In n8n, create a Swum API credential.
  3. Paste the key into Dedicated Swum n8n Key.
  4. Choose the Environment:
    • Live for your real school (sk_live_ keys).
    • DEV Sandbox for a Swum developer sandbox (sk_test_ keys). Live refuses test keys.
  5. Save. n8n checks the key by reading one family.

The key is sent only to https://api.swum.ai/v1 (Live) or https://swum-53cd2-api.web.app/v1 (DEV Sandbox), as a bearer token. Keep keys and webhook secrets out of execution output and shared workflow exports.

Swum node

Resource Operation What it does
Family Create Adds a family (parent or guardian) to the school roster
Family Search Finds families by name, email or swimmer name
Swimmer Add Adds a swimmer to a family
Swimmer Get Many Lists swimmers, for one family or the whole school
Enrollment Request Asks the school to enroll a swimmer in a class
Attendance Mark Present Marks a swimmer present for one dated class meeting
Message Send Sends a Swum message to 1 to 50 families

Source Action ID. Every write needs a stable Source Action ID, such as form-123:create-family. Use the same ID when you retry the same input and Swum will not do the action twice. Build it from the source record, for example {{ $json.submissionId }}:create-family.

Approvals. Actions run with the key's school, scopes and pool permissions. Enrollment requests and anything the school must approve come back with their real status, such as pending_approval. A pending result does not mean the swimmer is enrolled.

Limits. This node cannot charge cards, issue refunds, delete families or link accounts.

Search and Get Many return one item per family or swimmer. Turn on Return All to page through every result, or set Limit (1 to 200, default 50).

AI Agent. The Swum node can be used as a tool by n8n's AI Agent.

Errors. When Swum refuses a request, the node shows Swum's reason, for example "This request requires classes:write access." With Continue On Fail on, the item gets a short error message instead.

Swum Trigger

Pick one or more events:

Event When it fires
client.created A new family joins the school
lesson.booked A lesson is booked
lesson.canceled A lesson is canceled
enrollment.created A swimmer is enrolled in a class
payment.succeeded A payment goes through
payment.failed A payment fails
waiver.signed A family signs a waiver
level.advanced A swimmer moves up a level

When you activate the workflow, the trigger registers its webhook URL with Swum. When you deactivate it, the trigger removes it. Your n8n webhook URL must be public and use HTTPS on port 443. n8n Cloud URLs already do.

Every delivery is signed. The trigger checks the Swum-Signature header against the exact raw request bytes with HMAC-SHA256, and rejects altered, unsigned or expired (more than 5 minutes old) deliveries. The signing secret stays in the workflow's private node data. Swum may retry a delivery, so deduplicate downstream work by the event id.

Example workflows

1. Website sign-up to enrollment request

Turn a form submission into a family, a swimmer and an enrollment request the school approves.

  1. Webhook (or a Typeform, Jotform or Google Forms trigger) receives parentName, email, phone, childName, birthday, classId and a submissionId.
  2. Swum, Family > Create: Name {{ $json.body.parentName }}; Email and Phone under Additional Fields; Source Action ID {{ $json.body.submissionId }}:family.
  3. Swum, Swimmer > Add: Family ID {{ $json.id }}; Name {{ $('Webhook').item.json.body.childName }}; Birthday under Additional Fields; Source Action ID {{ $('Webhook').item.json.body.submissionId }}:swimmer.
  4. Swum, Enrollment > Request: Family ID, Swimmer ID and Class ID from the steps above; Source Action ID {{ $('Webhook').item.json.body.submissionId }}:enroll.

The school sees the request in Swum and approves it. If the workflow is retried, the same Source Action IDs are reused, so nothing is created twice.

2. Failed payment alert

  1. Swum Trigger with the event payment.failed.
  2. Slack (or Gmail, or Microsoft Teams) posts to the front desk with the family and amount from the event's data.

3. Pool closure message

  1. Manual Trigger (or a Schedule Trigger, or a weather check).
  2. Swum, Family > Search: leave Search empty and turn on Return All. Add a Filter node if only some families should hear about it.
  3. Aggregate collects the family id values into one list.
  4. Swum, Message > Send: Family IDs {{ $json.id.join(',') }} (up to 50 per message); Message "The pool is closed today. We will reach out to reschedule."; Source Action ID closure-{{ $now.toFormat('yyyy-MM-dd') }}.

Compatibility

Tested with n8n 2.45 on Node.js 22 and later. Version 0.2.0 replaced the single Fields list with resources and operations, so workflows built on 0.1.x need the Swum node set up again. See the changelog.

Development

npm install
npm run dev     # starts n8n at http://localhost:5678 with these nodes loaded
npm test        # builds, then runs the unit tests
npm run lint

Releases are published to npm by GitHub Actions, with npm provenance, when a v*.*.* tag is pushed. See .github/workflows/publish.yml.

Resources

Support

Email ben@swum.ai or open an issue.

License

MIT

Discussion