Skip to main content

Documentation Index

Fetch the complete documentation index at: https://try.materi.app/llms.txt

Use this file to discover all available pages before exploring further.

Shield includes a pipeline metrics webhook endpoint designed for services to report CI/CD outcomes. This recipe is aligned with domain/shield/apps/cicd/webhooks.py.

​
Endpoint

  • POST /api/v1/webhooks/pipeline-metrics/
  • GET /api/v1/webhooks/pipeline-metrics/ (health)

​
Required fields (minimum)

The implementation requires:
  • service
  • run_id
  • status
Other fields (pipeline name, branch, stages, etc.) are supported and recommended.

​
Example payload

{
    "service": "manuscript",
    "pipeline": "msx-ci",
    "run_id": "123",
    "run_number": "42",
    "status": "success",
    "branch": "main",
    "commit_sha": "abc123def456",
    "triggered_by": "developer1",
    "event": "push",
    "repository": "acme/app",
    "workflow_url": "https://github.com/acme/app/actions/runs/123",
    "stages": {
        "build": "success",
        "test": "success"
    },
    "timestamp": "2026-01-07T00:00:00Z"
}

​
Send it (signed)

Use the same signature header format as GitHub webhooks:
  • X-Hub-Signature-256: sha256=<hex>
This sends a JSON payload with a GitHub-style HMAC signature header. 
export WEBHOOK_BASE_URL="http://localhost:8000"
export GITHUB_WEBHOOK_SECRET="REPLACE_ME"

payload='{"service":"manuscript","pipeline":"msx-ci","run_id":"123","status":"success"}'

sig=$(python3 - <<'PY'
import hashlib, hmac, os
payload = os.environ["PAYLOAD"].encode("utf-8")
secret = os.environ["GITHUB_WEBHOOK_SECRET"].encode("utf-8")
print("sha256=" + hmac.new(secret, payload, hashlib.sha256).hexdigest())
PY
)

curl -sS "$WEBHOOK_BASE_URL/api/v1/webhooks/pipeline-metrics/" \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: pipeline_metrics" \
  -H "X-GitHub-Delivery: 123" \
  -H "X-Hub-Signature-256: $sig" \
  -d "$payload"
To reuse this snippet, set:
  • WEBHOOK_BASE_URL
  • GITHUB_WEBHOOK_SECRET
  • payload (and optionally X-GitHub-Delivery)
Update the snippet as follows:
  • Set the endpoint to POST /api/v1/webhooks/pipeline-metrics/
  • Set X-GitHub-Event: pipeline_metrics
  • Set X-GitHub-Delivery: <run_id>

​
Expected results

  • 202 or 200 JSON response indicating acceptance.
  • Metrics stored/forwarded according to Shield’s configuration.

​
Common failures

  • 401 Invalid signature: the secret doesn’t match GITHUB_WEBHOOK_SECRET in Shield.
  • 400 Missing required fields: ensure service, run_id, and status are present.