Secret scanning improvements to alert APIs, webhooks, and delegated workflows
Source: GitHub Changelog
Upcoming Improvements
This week we’re rolling out several enhancements to our APIs, webhooks, and delegated workflows. These updates reinforce our ongoing commitment to improving the developer experience for our secret‑scanning features.
- APIs – streamlined endpoints and clearer documentation.
- Webhooks – more reliable delivery and expanded event types.
- Delegated Workflows – simplified configuration and better error handling.
Built by developers, for developers.
What’s changing {#whats-changing}
Secret scanning introduces new API filters, richer webhook payloads, and enhancements to delegated‑alert workflows:
New
exclude_secret_typesfilter
The exclusion filter that’s already available in the GitHub UI (-secret-type:) can now be used via the REST API.html_urlon alert locations
Alert location objects now include a direct link (html_url) to the corresponding content on GitHub, both in the REST API responses and in webhook payloads.Delegated bypass‑email improvements
- Reviewers receive emails that show the expiry deadline for the bypass request.
- Developers get a confirmation email when they submit a dismissal request.
Closure‑request comments in API/webhooks
The requester’s comment, the reviewer’s comment, and the reviewer’s username are now included in the alert payloads for delegated closures.Bug fix
resolution_commentis no longernullwhen an alert is closed through delegated‑closure approval.
New exclude_secret_types API filter
GitHub frequently adds new secret types. When you rely on inclusion‑based filters, you must constantly update your scripts to handle these new patterns.
With an exclusion filter, you can simply specify the secret types you don’t care about, and any newly added types will be included automatically.
The Secret Scanning Alerts API now supports an exclude_secret_types query parameter. This lets you omit specific secret types from the results without having to list every type you want to keep.
Affected endpoints
All three list endpoints accept the new parameter:
GET /repos/{owner}/{repo}/secret-scanning/alertsGET /orgs/{org}/secret-scanning/alertsGET /enterprises/{enterprise}/secret-scanning/alerts
How to use
Pass a comma‑separated list of secret‑type slugs to the exclude_secret_types query parameter.
GET https://api.github.com/orgs/octo-org/secret-scanning/alerts?exclude_secret_types=aws_access_key,slack_tokenNote: Using both
secret_typeandexclude_secret_typesin the same request results in a 422 Unprocessable Entity error. Choose one approach or the other.
Alert location html_url field
Secret scanning alert locations in the REST API and webhook payloads now include an html_url field in the details object.
Previously, location details only returned API URLs (e.g., /repos/{owner}/{repo}/issues/comments/{id}), so if you were processing webhook events or building automation on top of the locations API you had to make additional API calls just to get a link you could actually click on or include in a notification.
Now the user‑facing URL is included directly. The field is additive— all existing URL fields are preserved.
Where the field is available
- REST API –
GET /repos/{owner}/{repo}/secret-scanning/alerts/{number}/locations - Webhook payloads – included in the
detailsobject of each location
Supported location types
| Location type | Example html_url (replace placeholders) |
|---|---|
commit | /{owner}/{repo}/blob/{sha}/{path}#L5-L5 |
issue_title / issue_body | /{owner}/{repo}/issues/{number} |
issue_comment | /{owner}/{repo}/issues/{number}#issuecomment-{id} |
pull_request_title / pull_request_body | /{owner}/{repo}/pull/{number} |
pull_request_comment | /{owner}/{repo}/pull/{number}#issuecomment-{id} |
pull_request_review | /{owner}/{repo}/pull/{number}#pullrequestreview-{id} |
pull_request_review_comment | /{owner}/{repo}/pull/{number}#discussion_r{id} |
Note: Replace
{owner},{repo},{sha},{path},{number},{id}with the appropriate values for your repository.
The html_url field provides a ready‑to‑click link for each alert location, simplifying automation and notification workflows.
Email notifications for delegated bypass requests
We’ve added two improvements to the email notifications sent during delegated bypass workflows.
1. Expiry notice
Email notifications for bypass and dismissal requests now include the request’s expiration period, so reviewers know how long they have to act before the request is automatically closed.
| Request type | Expiration period |
|---|---|
| Push‑protection bypass | 7 days |
| Alert dismissal (short‑term) | 30 days |
| Alert dismissal (long‑term) | 1 year |
Previously there was no way to tell the deadline from the email alone.
2. Developer confirmation email
Developers now receive a confirmation email when they submit an alert‑dismissal request, letting them know the request is pending review.
Before: only reviewers were notified; the submitter got no feedback until the request was approved or denied.
New fields on secret‑scanning alert payloads
When an alert has a delegated closure (dismissal) request, three additional fields are included in the API and webhook payloads:
| Field | Description |
|---|---|
closure_request_comment | The requester’s comment explaining why they want to close the alert. |
closure_request_reviewer_comment | The reviewer’s response comment. |
closure_request_reviewer | The reviewer’s user object. |
These fields follow the same model as the existing push‑protection bypass fields (push_protection_bypass_request_comment, push_protection_bypass_request_reviewer_comment).
Use cases: tracking why alerts were dismissed, auditing reviewer decisions, or syncing with external ticketing systems—now possible directly from the payload without extra look‑ups.
Bug fix
A bug caused resolution_comment to be null on alerts closed through the delegated alert‑closure approval flow. The requester’s comment was stored on the exemption request but not forwarded to the alert.
Fix: the comment is now correctly passed to the alert’s resolution_comment field, matching the behavior of direct dismissals via the REST API.
Learn more
- Secret scanning overview – GitHub Docs
- Secret scanning REST API – GitHub REST API documentation
- Community discussion – Share your thoughts and feedback in the GitHub community forum