CI Event Validation

Use CI event validation when your application keeps example payloads, contract fixtures, or event builder tests in the repository.

Validate a fixture

Run the CLI with --json so CI can parse the output:

saasfunnels events validate ./saasfunnels-event.json --source direct --json

The command exits non-zero when validation fails. Treat that as a build failure.

Suggested workflow

1. Keep one or more sanitized event fixtures in the repository.
2. Run saasfunnels events validate for each fixture.
3. Fail the job on missing account identity, unsafe fields, invalid semantic types, or missing idempotency keys.
4. Keep smoke-event sends out of normal CI unless the job runs in a safe staging environment.

Example:

saasfunnels events validate ./fixtures/saasfunnels/usage-limit-hit.json --source direct --json
saasfunnels events validate ./fixtures/saasfunnels/checkout-started.json --source direct --json

What validation catches

• Missing account identity.
• Invalid semantic types.
• Oversized or unsafe event names.
• Token-like or email-like unsafe fields.
• Missing stable idempotency keys.
• Non-revenue-relevant payload warnings.
• Signal-family mapping hints.

Secret handling in CI

Payload validation is local and does not need a key. Do not add SAASFUNNELS_API_KEY or SAASFUNNELS_INGEST_API_KEY to validation-only jobs.

If a staging job sends a setup smoke event, scope SAASFUNNELS_INGEST_API_KEY to the staging workspace and keep the command explicit:

SAASFUNNELS_INGEST_API_KEY=<SAASFUNNELS_INGEST_KEY> saasfunnels events send-test --file ./fixtures/saasfunnels/usage-limit-hit.json --json

Related articles

• SaaSFunnels CLI
• API Keys and Scopes
• Data Safety and Security Boundaries