Setting Up External Agreement Integrations

Lumieos can receive agreement completions from external signing tools (Jotform, Smartwaiver) via webhook, and can automatically mark agreements complete from FIRST’s Consent & Release status during Tableau import. This guide walks through configuring both paths.

Writing your own agreements? To create an agreement that people accept inside Lumieos — and to say which roles have to sign it — see Creating & Managing Agreements. This page covers only agreements signed somewhere else.

Tip: Use the instance selector in the top navigation bar to personalize every admin URL on this page to your deployment. Until you pick one, URLs show a <your instance> placeholder.

Overview

Three integration paths populate the electronic_external signature method on Agreements:

All three paths share idempotent completion — re-delivering the same webhook or re-running the same import never double-marks an agreement or mutates chain-of-custody fields.

Admin URL: https://<your instance>/en/region/agreements

Step 1 — Choose the AgreementType’s external tool

Admin URL: https://<your instance>/en/region/agreements

Agreement types created through the admin can optionally point at an external signing tool. Open Region Management → Configuration → Agreements → Agreement Types, click an agreement type, and fill in:

Note: Field mapping is only used when a webhook arrives without our token — for example, if a user fills out the Jotform form directly from a bookmark or shared link instead of clicking the “Sign with Jotform” button in Lumieos. The token path is preferred; the field-mapping fallback exists so direct-link submissions still match up.

Step 2 — Configure per-provider webhook secrets

Open Region Management → Configuration → Agreements → Webhook Secrets. The two providers protect their webhook differently: Smartwaiver signs its deliveries with a per-partner HMAC secret you paste in from its own dashboard, while Jotform signs nothing at all, so Lumieos generates a secret and builds it directly into Jotform’s Webhook URL instead. See each provider’s steps below.

Warning: Smartwaiver’s secret is write-only — Lumieos never returns the stored value in any API response. If you lose it, rotate it in both Lumieos and Smartwaiver.

Jotform

Jotform doesn’t sign its webhook deliveries and offers no shared-secret option of its own — there’s nothing on Jotform’s side to configure for authentication. Instead, Lumieos generates a secret and embeds it directly in the Webhook URL, so the URL itself is what proves a delivery is legitimate.

1. On Region Management → Configuration → Agreements → Webhook Secrets, the Jotform row shows a Configured / Not configured chip. Click Generate secret (or Rotate secret, once one already exists).
2. Copy the Webhook URL the page produces — it has a copy button next to the field, so there’s no need to retype it. It’s built from your own partner domain plus the secret you just generated, so it reads https://<your partner domain>/api/agreements/webhook/jotform/<partner-id>/<secret>/.
3. Go to your Jotform form → Settings → Integrations, search for Webhooks, add a new webhook, and paste that URL in.
4. Back on the form editor, make sure the field names Lumieos expects (from your field-mapping JSON) actually match your form’s question names. Jotform question names look like q5_teamNumber — you can see them in the form’s URL params or via the form’s Export submission data view.

Warning: Rotating (or generating for the first time) replaces the URL immediately — the previous one stops working right away. Paste the new URL into Jotform before submissions start bouncing.

Note: If your Webhook Secrets page previously showed a value entered for Jotform, that setting could never actually verify a real Jotform delivery — Jotform has nothing on its end to sign with it. You’ll see Not configured now; click Generate secret to secure the webhook for real.

Tip: For the token path, Jotform preserves URL query params (like ?ref=<token>) through the submission and echoes them back in the rawRequest payload — no special configuration needed.

Smartwaiver

1. Go to your Smartwaiver template → Settings → Webhooks
2. On the same Region Management → Configuration → Agreements → Webhook Secrets page, copy the Webhook URL shown next to Smartwaiver (again via its copy button) — it’s your own partner domain plus /api/agreements/webhook/smartwaiver/<partner-id>/
3. Set the signing key to match the Smartwaiver secret you set in Lumieos
4. Tokens ride the tag URL parameter on the signing URL and come back as waiver.tag in the webhook payload — no extra setup needed

Step 3 — Test the webhook plumbing

Trigger a test submission from the provider. On Region Management → Configuration → Agreements → Webhook Secrets, the Webhook history panel shows every recent delivery:

Click a row to expand the raw + processed payloads — helpful for diagnosing field-mapping mismatches.

Note: Unmatched submissions still return HTTP 200 to the provider (so they don’t retry forever). They sit in the history as “Matched: No” so an admin can investigate.

FIRST Consent & Release Integration

FIRST exposes a Consent Release Status field on volunteer and student records. When that value is Accepted during a Tableau import, Lumieos can automatically complete a matching agreement record.

Set up automatically

You do not have to configure anything for this to work. The first time an import reads an accepted consent, Lumieos creates the two agreements it needs and links them:

• FIRST Youth Protection Program (Volunteer)
• FIRST Consent and Release (Youth)

These are signed with FIRST rather than in Lumieos, so they carry no wording of their own — they exist to hold the completion and its signing record. They will show as having nothing published, which is expected.

Existing regions had these created for them when 26.3.4 was applied, so you can review the links before your next import.

Previously, an unconfigured region silently discarded every imported consent. If you are wondering why consents from earlier imports were never recorded, that is why. Re-running the import will record them.

Pointing them at your own agreements instead

If you would rather use agreements you have already created, change the link and Lumieos will leave your choice alone from then on.

Admin URL: https://<your instance>/en/region/agreements

Admin URL: https://<your instance>/en/region/agreements

Open the FIRST Mapping panel from the Agreement Types tab. The two fields are named for the FIRST documents they record:

• Youth Protection Program (volunteers) — matched against NationalVolunteerRecord.consent_form_status during VMS imports
• Consent and Release (youth) — matched against StudentMemberRecord.consent_form_status during roster imports

Leave either dropdown on (none — opt out) to skip that half of the integration.

Step C — Run a Tableau import

Any normal Tableau import will now auto-complete the mapped AgreementType for every volunteer/youth record with Accepted status. The completion uses:

Note: Import is forward-only. Existing Accepted statuses in historical records won’t be backfilled — only new imports after the mapping is configured trigger the integration.

Tip: Re-running the same import is safe — the idempotency check (external_reference_id match on an already-complete agreement) short-circuits the update.

Troubleshooting

Webhook signature verification fails: Double-check the shared secret matches on both ends. Lumieos rotates the stored value on save, so if you recently rotated, re-paste into the provider too.

Webhook arrives as “Unmatched”: The token was missing/expired, and the field mapping couldn’t resolve a FormationTeamMember. Verify the field mapping JSON matches actual Jotform question names (or the Smartwaiver template ID is set).

FIRST import runs but no agreements complete: Check the FIRST Mapping panel shows an agreement against both entries. Since 26.3.4 these are created automatically on first use, so an empty mapping usually means the import has not yet seen an accepted consent. Before 26.3.4 an unconfigured region skipped silently, which is the most likely explanation for consents missing from earlier imports.

Concurrent webhook deliveries: Providers sometimes deliver the same event twice. The completion helper uses SELECT FOR UPDATE on the Agreement row inside a transaction, so the second caller sees the completed state and returns the idempotency no-op.

Manual Completion

Some agreements can’t be electronically signed and can’t be imported from FIRST — e.g., a paper form in a filing cabinet, or a completion verified through some offline channel. Partner admins can mark such agreements complete from the region-admin Agreements page.

Admin URL: https://<your instance>/en/region/agreements

Global view

Switch to the Agreements tab on the region Agreements page. The table shows every agreement (defaulting to “Not finished”) across all teams in your partner. Filter by status, agreement type, signature method, or team number.

Select one or more rows via the checkboxes and click Mark complete (N) to open the completion dialog.

Per-team view

On the Teams page, click the file-signature icon in a team’s actions column to open the team-scoped agreements drawer. The drawer shows the same table filtered to that team — useful when processing a stack of paper forms one team at a time.

Completion methods

Bulk completion only applies to paper_onfile. A single scanned file cannot represent multiple people, so the dialog disables “paper upload” when more than one row is selected.

Audit trail

Every manual completion records:

• The admin user who marked it (paper_verified_by)
• The moment they clicked save (paper_verified_at)
• The signed date the admin typed in (paper_signed_date)
• The notes or uploaded file (paper_signature_notes / paper_signature_file)
• A tamper-evident signature_hash computed over the chain-of-custody fields

Manually-completed agreements auto-lock the same way electronically-signed ones do. Un-marking requires support intervention — same policy as any other completion method.

Tip: The “Not finished” filter is the default for a reason — focus on what still needs doing. Switch to “All” or “Complete” to audit the outcome afterwards.

User-Account Coaches

On US-based teams where coaches have Lumieos accounts, their agreements are now tracked through the same chain-of-custody system as formation members — but with one important difference: a user-account coach’s agreements are per-coach, not per-team. A coach who serves three teams signs each required form once, and completion flips the status on every team they coach.

The team documentation tab surfaces user-account coaches alongside formation members. Their rows are labeled “Applies to all teams” to make the cross-team scope explicit. Coaches sign at /account/agreements — admins don’t sign on a coach’s behalf from the doc tab.

Admin overrides (paper on file, paper upload) for user-account coaches live on the region admin Agreements page, same as for formation members. Filter by team number to see all agreements for that team’s coaches and members in one list.