Webhook icon
Schedule icon
Script icon
Process icon
If icon
Create icon
SlackIncomingWebhook icon
Log icon

Segment Event Taxonomy and Property Contract Validator

Check Segment event names and required property types against a taxonomy contract, then escalate violations as a GitHub issue and a Slack digest.

Categories
BusinessData

Segment keeps sending events, the tracking plan keeps drifting, and the first sign of it is a dashboard nobody trusts anymore. This blueprint turns the taxonomy into an executable contract: the webhook body is normalized into an event batch, every name is checked against a lowercase snake_case rule plus a track_ prefix requirement for track calls, and each known event is checked for its required properties with declared types (string, int, or bool). Violations are grouped by rule, the top offenders are opened as a GitHub issue, and a Slack digest announces the counts while clean batches log quietly and expose their verdict as flow outputs.

How it works

  1. The segment_webhook trigger (io.kestra.plugin.core.trigger.Webhook) exposes a keyed URL that your Segment Webhooks destination, source function, or HTTP API call POSTs to, and the daily_digest trigger (io.kestra.plugin.core.trigger.Schedule, cron 0 6 * * *) ships with disabled: true for a once-a-day sweep.
  2. extract_events (io.kestra.plugin.scripts.python.Script on the io.kestra.plugin.core.runner.Process runner) reads {{ trigger.body ?? '' }}, accepts a single message, a batch wrapper, or a raw array, caps the batch at the sample_limit input, and falls back to a built-in sample when no body is present. It emits source, event_count, event_names, events_json, and parse_error through Kestra's outputs protocol.
  3. check_taxonomy applies the contract: names must match ^[a-z][a-z0-9]*(_[a-z0-9]+)*$, events with type: track must start with track_, and every known event must carry its required properties with the declared type (a bool is not an int). It emits verdict, violation_count, unknown_count, the grouped violations_by_rule, offending_events, unknown_names, a pair of ready-to-post summary strings, and a single-line report.
  4. escalate_violations (io.kestra.plugin.core.flow.If) branches when violation_count > 0. Over zero, create_issue (io.kestra.plugin.github.issues.Create) opens a labeled issue carrying the top offenders and unknown names, and slack_digest posts the counts; at zero, log_clean records the all-clear for the execution history.
  5. The errors block posts to Slack when the validation itself fails, so a broken check is never mistaken for a clean taxonomy.

What you get

  • A webhook endpoint that turns every Segment batch into a pass or fail verdict within seconds.
  • Violations grouped by rule (naming, track prefix, missing property, type mismatch, unknown event) inside one report string.
  • A GitHub issue that lists the top offenders and unknown names, labeled for the analytics backlog.
  • A Slack digest with the counts, so the team sees drift without opening Kestra.
  • Flow outputs (violation_count, unknown_count, verdict, report) that dashboards and parent flows can consume.

Who it's for

  • Analytics engineers who own a tracking plan and want drift caught before it reaches the warehouse.
  • Data platform teams that gate incoming event streams on a naming and property contract.
  • Product teams standardizing track vocabulary across web, mobile, and server-side sources.

Why orchestrate this with Kestra

A contract check that nobody runs catches nothing, and a check buried inside a Segment Function has no history, no retries, and no way to file work when it trips. Kestra supplies the loop around the check: a keyed webhook trigger for real batches plus a disabled daily schedule for rehearsing the contract, a declarative If that separates escalation from the all-clear, and execution history that proves the sweep ran. Escalation itself is orchestration, opening a GitHub issue and posting a Slack digest from the same versioned file instead of a hand-rolled script with its own credentials. Inputs let you retarget the repository and environment per execution, and outputs make the verdict available to anything downstream.

Prerequisites

  • A Kestra instance with the GitHub and Slack plugins available, and Python 3 on the worker (the two script tasks use the Process runner).
  • A Segment source that can POST to a webhook (the Webhooks destination, a source function, or a direct HTTP API batch call).
  • A GitHub repository that allows issue creation with the provided token (classic PAT scope repo, or fine-grained Issues: write).
  • A Slack incoming webhook for the digest and the failure alert.

Secrets

  • SEGMENT_WEBHOOK_KEY: key segment guarding the webhook URL, treat it as a secret since anyone holding it can start executions.
  • GITHUB_TOKEN: token used for jwtToken to open the violation issue in issue_repository.
  • SLACK_WEBHOOK_URL: Slack incoming webhook URL used by the digest and the errors alert.

Quick start

  1. Add the three secrets (SEGMENT_WEBHOOK_KEY, GITHUB_TOKEN, SLACK_WEBHOOK_URL) to the Kestra namespace.

  2. Set issue_repository to the owner/repo that should receive taxonomy issues, and set environment if the batch is not production.

  3. The flow ships with both triggers already declared, one keyed webhook and one schedule disabled on purpose:

    triggers:
      - id: segment_webhook
        type: io.kestra.plugin.core.trigger.Webhook
        key: "{{ secret('SEGMENT_WEBHOOK_KEY') }}"
      - id: daily_digest
        type: io.kestra.plugin.core.trigger.Schedule
        cron: "0 6 * * *"
        disabled: true
    
  4. Point the Segment Webhooks destination at /api/v1/{tenant}/executions/webhook/{namespace}/segment-event-taxonomy-validator/{SEGMENT_WEBHOOK_KEY} and POST a test event:

    curl -X POST "$WEBHOOK_URL" \
      -H "Content-Type: application/json" \
      -d '{"type":"track","event":"Track Page Viewed","properties":{"page_path":"/pricing"}}'
    

    Expect an execution reporting violations_found that opens the GitHub issue and posts the Slack digest, then POST a compliant track_page_viewed event and expect log_clean with verdict: pass.

How to extend

  • Edit the CONTRACT map inside check_taxonomy to register events and their required properties, using the types string, int, and bool.
  • Tighten NAME_RE (for example require a source prefix such as web_) and adjust the track_ prefix rule to match your naming standard.
  • Fan large payloads out with an io.kestra.plugin.core.flow.Loop over chunked batches, keeping the same check script per chunk.
  • Replace create_issue with a pull request that updates the tracking plan document, or land report into a warehouse table with a JDBC query task.

Links

See How

New to Kestra?

Use blueprints to kickstart your first workflows.