Webhook Reporter
Overview
The Webhook Reporter POSTs validation results as a JSON payload to an HTTP endpoint. It supports custom request headers, bearer token authentication, and SSRF protection (local/private addresses are blocked by default).
This reporter is useful for integrating Karandash with custom dashboards, notification systems, ticketing tools, or any service that can receive HTTP POST requests.
How it works
The Webhook reporter composes two modules:
WebhookOutputModule- handles HTTP POST delivery, auth headers, and SSRF protection; requests go through the shared HTTP client, which supplies the default retry policy (ProviderHttpClientFactory)- A format module (defaults to JSON) - serializes findings into the request body
By default the payload uses the JSON format. To POST a different format (e.g., Markdown), configure explicit format+output composition via the advanced reporter config.
Configuration
YAML
reporters:
webhook:
url: "https://hooks.example.com/karandash"
With Authentication
reporters:
webhook:
url: "https://hooks.example.com/karandash"
auth-token: "${WEBHOOK_SECRET}"
headers:
X-Source: "karandash"
X-Environment: "production"
JSON
{
"reporters": {
"webhook": {
"url": "https://hooks.example.com/karandash",
"authToken": "${WEBHOOK_SECRET}"
}
}
}
Options
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
url |
string | Yes | - | HTTPS URL to POST results to |
headers |
map | No | {} |
Additional HTTP headers to include; names are sent exactly as written (X-Source stays X-Source) |
authToken |
string | No | - | Bearer token added to the Authorization header |
contentType |
string | No | application/json |
Content-Type of the POSTed body (set it when posting a non-JSON format) |
onError |
string | No | fail |
fail: a failed POST (bad URL, connection error, non-2xx response) fails the output and the run exits 6 (EXECUTION_ERROR) when it would otherwise pass; warn: the failure is only logged |
when |
string | No | always |
Which runs deliver: always, changed (the verdict or the set of findings differs from the last platform summary comment; a run without a platform counts as changed), failed, never |
The auth token and the custom headers are sent only to the webhook URL's host: a request that leaves it (a redirect to another host) carries neither.
Payload Format
The reporter POSTs a compact JSON body with Content-Type: application/json:
{
"status": "FAIL",
"findings": [
{
"severity": "ERROR",
"rule": "title-format",
"message": "MR title does not match required pattern: ^(feat|fix): .+",
"location": null
},
{
"severity": "ERROR",
"rule": "security",
"message": "Potential secret detected",
"location": {
"file": "src/config.py",
"line": 42
}
}
],
"summary": {
"errors": 2,
"warnings": 0,
"info": 0,
"total": 2
}
}
Payload Fields
Top level:
| Field | Type | Description |
|---|---|---|
status |
string | "PASS" or "FAIL" |
findings |
array | List of all findings |
summary |
object | Counts by severity |
Finding object:
| Field | Type | Description |
|---|---|---|
severity |
string | "ERROR", "WARNING", or "INFO" (uppercase) |
rule |
string | Rule ID |
message |
string | Finding message |
location |
object or null | File and line, if available |
Location object:
| Field | Type | Description |
|---|---|---|
file |
string or null | File path |
line |
integer or null | Line number (1-based) |
Summary object:
| Field | Type | Description |
|---|---|---|
errors |
integer | Error count |
warnings |
integer | Warning count |
info |
integer | Info count |
total |
integer | Total findings |
Authentication
When authToken is set, the reporter adds an Authorization: Bearer {token} header to the request.
reporters:
webhook:
url: "https://api.example.com/karandash/results"
auth-token: "${WEBHOOK_TOKEN}"
Error Handling
A failed POST (bad or blocked URL, connection error, non-2xx response) is always logged at warn. What happens next is set by onError:
fail(default): the output fails, and a run that would otherwise pass exits 6 (EXECUTION_ERROR). A run that already fails on its findings keeps its own exit code.warn: the failure is only logged and the exit code is unchanged.
The request goes through the run's http.retry policy. Because a POST is not idempotent, it is retried only when the server cannot have acted on it: a 429 answer or a connect timeout. Other failures are not retried.
SSRF Protection
The webhook URL is validated by SsrfUrlValidator before each request. Requests to private IP ranges, loopback addresses (127.x.x.x, ::1), and link-local addresses are blocked by default. This protection can be disabled for local endpoints with allow-localhost: true in the config (or --allow-localhost); the URL check and the HTTP client both honour it. For a webhook on an internal network, allow-private-network: true permits private and dotless hosts only, keeping the loopback, metadata and HTTPS checks.
Notes
- The
urlfield is required and must be non-empty, or the reporter throwsIllegalArgumentExceptionat report time. - Severity values in the payload are uppercase strings (
"ERROR","WARNING","INFO"), unlike the JSON reporter which uses lowercase. - A failed POST affects the exit code only under the default
onError: fail; setonError: warnto keep it advisory.