API Reference

Interactive, always-current API docs are served by the running application itself at /swagger. This page is a quick map of what exists and how it’s authenticated.

GitHub webhooks

POST /GitHub

Receives a GitHub webhook payload (application/json).

  • Signature is validated by GitHubSignatureValidationMiddleware against the configured GitHub webhook secret before the controller runs.
  • A valid signature forwards the payload to the broker and returns 202 Accepted.
  • An invalid signature returns 401 Unauthorized. The payload is still logged, not silently dropped.
  • If every configured broker connection has reached its monthly message limit, the payload is not published and the response is 503 Service Unavailable with a ProblemDetails body whose detail names the period and the connections checked. The failure is logged and reported to Projects Monitor. Redeliver from GitHub’s webhook log once there is capacity again (a new month, a raised limit, or an added connection) — see Configuration.
  • Unhandled errors while publishing to the broker are logged to Projects Monitor and return 400 Bad Request.

Response body

Both 202 Accepted and 401 Unauthorized carry the same JSON body describing how the delivery was handled:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
  "id": "5d4132a6-5759-47a9-83b5-ad7c37a9ec3e",
  "time": 1788096416,
  "isSignatureValid": true,
  "priority": {
    "eventType": "workflow_run",
    "action": "completed",
    "senderLogin": "github-advanced-security[bot] [BOT]",
    "baseScore": 3,
    "actionModifier": 0,
    "baseCalculatedScore": 3,
    "senderMultiplier": 0.7,
    "finalScore": 2,
    "description": "Very Low - Monitoring Events",
    "isCoreFunction": false
  },
  "broker": "BROKER_URL_1",
  "version": "1.5.2"
}
Property Description
id Unique id assigned to this delivery. The same id is stamped on the message published to the broker, so a response can be matched to what the consumer receives
time Unix timestamp (seconds, UTC) at which the request was handled
isSignatureValid Whether X-Hub-Signature-256 matched the configured webhook secret
priority Scoring result for the event (type, action, sender, score breakdown). finalScore is used as the message priority on the broker
broker Name of the broker connection the payload was published through, e.g. BROKER_URL_1. Matches the name reported by GET /Broker/connections and the broker key in the usage endpoints, so a delivery can be traced to a specific broker when several are configured
version Version of the handler that processed the request

Properties are only ever added to this body, never renamed or removed, so consumers should ignore properties they do not recognise.

Broker administration

All /Broker/* routes require Authorization: Bearer <token>, checked by BrokerAuthMiddleware against Broker:AuthToken.

Method Route Description
GET /Broker/connections List configured broker connections and which one is active
POST /Broker/switch/{index} Switch the active broker connection (1-based index). If that connection is already at its monthly limit, the next message rotates away from it again
POST /Broker/reload Reload the connection list (and any BROKER_LIMIT_N overrides) from .env without restarting the process
GET /broker/usage/current Message usage for every configured broker for the current calendar month, including each broker’s effective monthly limit and remaining messages
GET /broker/usage Message usage for all brokers across every stored month (historical)
DELETE /broker/usage?olderThan={yyyy-MM} Delete usage data for periods strictly before olderThan. Never deletes the current month, even if olderThan is in the future
DELETE /broker/usage/{period} Delete usage data for one specific month (yyyy-MM). Rejected with 400 if period is the current month
DELETE /broker/usage/current/{broker} Reset the current month’s usage for one specific broker only, leaving other brokers and historical data untouched

Before each publish the handler reserves one message against the chosen broker’s counter for the current month; a failed publish gives it back. Counts are tracked per broker and reset naturally when the calendar month rolls over. The limit reported as monthlyLimit is the broker’s effective one: BROKER_LIMIT_N from .env when set, otherwise Broker:MonthlyMessageLimit (default 2,000,000, CloudAMQP’s free LavinMQ tier cap). Once a broker’s count reaches its limit the handler routes new messages to the next configured broker automatically — see Configuration and Architecture.

Because routing is driven by these counters, DELETE /broker/usage/current/{broker} re-opens that broker with a full month of capacity.

Stats

GET /Stats

Per-GitHub-sender webhook activity stats. Distinct from broker message usage — see Architecture.

Health

GET /api/health

Reports API and RabbitMQ/broker connectivity health. Polled by UptimeRobot every 5 minutes in production.

Root

GET / redirects (permanent) to /swagger/index.html.