GitHub Webhooks

Set up GitHub webhooks to automatically trigger Oathe audits on push and release events.

What Webhooks Do

GitHub webhooks let you automatically trigger an Oathe audit whenever code changes land in your repository. Instead of manually submitting URLs, you configure GitHub to notify Oathe on push and release events. Oathe receives the event, identifies the affected skill, and queues an audit.

Getting Started

Webhook integration requires a shared secret between your GitHub repository and Oathe. To get set up, contact us — we’ll provision your webhook credentials and guide you through configuring the webhook in your GitHub repository settings.

Once configured, Oathe verifies the X-Hub-Signature-256 header on every delivery. Requests with an invalid or missing signature are rejected.

Supported Events

Push

A push event triggers an audit when the push modifies files inside a recognized skill directory. Oathe inspects the list of changed files in the payload and scopes the audit to the affected subdirectory. Pushes that do not touch skill-related files are acknowledged but do not start an audit.

Release

A release event triggers a full audit of the repository at the tagged commit. This is useful for running a final scan before a version is published or distributed.

Commit Status Reporting

After an audit completes, Oathe posts a commit status back to GitHub on the relevant SHA. The status context is oathe/audit and the state maps to the audit recommendation:

VerdictCommit Status
SAFEsuccess
CAUTIONsuccess
DANGEROUSfailure
MALICIOUSerror

The status description includes the trust score and a link to the full report.

Response Format

Oathe responds to valid webhook deliveries with 200 OK and a JSON body:

{
  "accepted": true,
  "audit_id": "abc123",
  "event": "push"
}

If the event does not match a supported type or the signature fails, the response includes an error field explaining the rejection.