GitHub Secret Scanning Webhook secret_category: Update Alert Routing Safely

GitHub has added a secret_category field to the secret_scanning_alert webhook payload. The field distinguishes default detections—provider patterns and custom patterns—from generic detections, including generic patterns and AI-detected secrets. That sounds like a small schema change, but it affects queue routing, dashboards, escalation rules, and any parser that rejects unknown fields.

GitHub documents the field and category meanings in its July 15, 2026 changelog. GitHub also announced APIclub and Resend detectors, default push protection for VolcEngine Ark API keys, and new public-monitoring insight cards. The migration workflow below is inferred defensive guidance. CodeRiskTools did not test GitHub’s hosted detection service, measure detector accuracy, or validate public-monitoring counts. Use synthetic, redacted payloads and your own delivery logs before changing production routing.

What changed in the secret scanning event

The new category is an alert-routing attribute, not a risk score. A provider pattern can identify a recognizable token format, while a generic or AI-detected pattern can surface a broader signal. Neither category proves that a credential is active, exploitable, owned by your organization, or safe to dismiss. Severity and response priority still depend on exposure, validity where supported, repository context, permissions, and the affected system.

Inventory consumers before changing a rule

List every consumer of secret_scanning_alert: webhook gateways, serverless handlers, message queues, SIEM transforms, ticket creators, metrics jobs, data warehouses, and replay tools. Record which component verifies the webhook signature, which component parses JSON, and which component makes the final routing decision. Strict closed-schema validators may fail merely because a legitimate new field appears; permissive parsers may accept it but never expose it downstream.

Also separate the alert event from secret_scanning_alert_location, which reports activity about alert locations. GitHub’s webhook documentation treats them as distinct event types. Do not infer that a location event contains the same fields or that one delivery can replace the other.

A seven-step schema-tolerant rollout

1. Freeze the baseline. Save the deployed parser version, routing table, queue names, event types, and current delivery success/error counts.
2. Capture a redacted fixture. Preserve headers needed for testing, action, repository identity, alert number, secret type, resolution fields, and category. Replace the secret itself with a synthetic non-credential value.
3. Extend the internal model. Add an optional category field with an explicit enum adapter: default, generic, missing, and unknown. Keep raw unknown values only in access-controlled diagnostics.
4. Keep parsing separate from policy. First prove that valid old and new events deserialize. Then apply routing rules in a second stage so schema acceptance does not silently become an escalation decision.
5. Shadow the new route. Compute old and proposed destinations without changing ticket ownership. Compare counts by event ID and explain every mismatch.
6. Canary one bounded lane. Enable category-aware routing for a small repository set or queue while retaining a reversible fallback.
7. Reconcile after rollout. Compare webhook deliveries, accepted events, queued events, tickets, and terminal outcomes. Missing records are failures, not zero-risk results.

Build a synthetic test matrix

Use byte-stable fixtures that cannot be mistaken for real credentials. Test opened, resolved, reopened, assigned, and other actions your integration supports. Include duplicate delivery IDs, out-of-order events, missing optional properties, an unknown category, invalid JSON, an invalid signature, and a temporary queue failure. A retry must be idempotent: the same delivery should not create a second incident or erase the first decision.

• A valid default fixture reaches the expected queue exactly once.
• A valid generic fixture reaches its review lane without being auto-dismissed.
• A legacy fixture with no category remains processable and visibly labelled.
• An unknown category fails closed into review rather than being coerced to default.
• Invalid signatures are rejected before payload-derived routing or logging.
• Logs and dead-letter records contain no secret value or reusable authorization header.
• Replay after a transient failure produces one final ticket and one auditable outcome.

Do not turn category into a severity shortcut

The category tells you which pattern family produced the alert. It does not say whether the secret is valid. GitHub’s supported-pattern table documents provider-specific capabilities such as push protection and validity checks; those capabilities vary by secret type. Check the current table rather than maintaining a stale assumption in code.

A defensible triage record links the alert number, repository, location, secret type, category, validity status when available, exposure window, owner, revocation evidence, remediation commit, and final resolution. Never copy the detected secret into a ticket, chat message, screenshot, or public benchmark. If a token may be live, rotate or revoke it through the provider’s documented process; deleting a line from Git does not invalidate the credential.

Reconcile the other July 15 changes separately

GitHub says secret scanning now detects apiclub_api_key and resend_api_key. It also says public-repository partner secrets can be forwarded to the issuer, and that VolcEngine volcengine_ark_api_key is included in push protection by default for repositories with secret scanning enabled. Verify current entitlement and repository settings; do not infer complete organization coverage from the announcement.

The new public-monitoring cards summarize attribution, enterprise member count, and verified domains. Treat those as navigation and scoping signals, not unique-secret counts or proof that every leak belongs to the enterprise. Preserve the underlying alert identifiers when reconciling dashboards with webhook and ticket data.

Production readiness checklist

• Webhook signatures are verified against the exact raw request body before parsing.
• Old, new, missing-category, and unknown-category fixtures have explicit expected outcomes.
• Default and generic queues have named owners and response objectives.
• No routing rule automatically dismisses an alert because of its category.
• Delivery, parse, queue, ticket, and closure counts reconcile by immutable event identity.
• Retries are bounded and idempotent; dead-letter handling is monitored.
• Logs, fixtures, test reports, and tickets are scanned for accidental secret values.
• The rollback restores the previous routing policy without discarding newly accepted events.

FAQ

Should generic detections always be lower priority?

No. GitHub’s category labels identify pattern groups, not business impact or credential validity. Use exposure and system context to prioritize an individual alert.

Can I require secret_category immediately?

Avoid an abrupt requirement if you replay historical fixtures or have multiple producers. Accept a missing value explicitly, measure it, and tighten the contract only after every legitimate source is reconciled.

Does push protection mean no secret reached GitHub?

Not universally. It applies to supported patterns and enabled contexts, and users may have documented bypass paths. Review alerts and repository settings rather than treating one blocked push as complete coverage.

Does removing a leaked token from the repository finish remediation?

No. Revoke or rotate the credential, investigate use, remove it from reachable history where appropriate, and document the replacement and exposure window without reproducing the secret.

Official sources and next step

• GitHub Changelog: secret scanning and public monitoring improvements — vendor documentation for the new field, detectors, push-protection default, and insight cards.
• GitHub Docs: webhook events and payloads — current event types, actions, and payload contracts.
• GitHub Docs: evaluating secret scanning alerts — official alert-triage guidance and webhook/API references.
• GitHub Docs: supported secret scanning patterns — current pattern capabilities, including push protection and validity support.

Continue with the CodeRiskTools guides for triaging secret scanning metadata, secret scanning AI-assisted changes, and pre-commit checks. The single comparison hub separates workflow scope without turning feature lists into security guarantees.