Test the Shield GitHub Actions webhook locally

This recipe helps you validate the Shield CI/CD webhook receiver end-to-end. It is based on the implementation in domain/shield/apps/cicd/webhooks.py.

Prerequisites

Shield running locally.
GITHUB_WEBHOOK_SECRET configured for the Shield service (this is what the code reads).

1) Confirm the health endpoint

By default, the GitHub Actions webhook routes are mounted under:

GET /api/v1/webhooks/github-actions/health

export SHIELD_BASE_URL="http://localhost:8000"
curl -sS "$SHIELD_BASE_URL/api/v1/webhooks/github-actions/health" | cat

If this does not return 200/healthy, check Shield routing and logs.

2) Send a signed workflow_run payload

Create a minimal payload (this is a small subset of what GitHub sends):

payload='{
  "action": "completed",
  "workflow_run": {
    "id": 123456,
    "run_number": 1,
    "status": "completed",
    "conclusion": "success",
    "head_branch": "main",
    "head_sha": "abc123",
    "html_url": "https://github.com/acme/app/actions/runs/123",
    "created_at": "2025-01-01T10:00:00Z",
    "updated_at": "2025-01-01T11:00:00Z",
    "actor": { "login": "developer1" },
    "name": "CI Pipeline",
    "workflow_id": 789,
    "run_attempt": 1,
    "event": "push"
  },
  "repository": {
    "full_name": "acme/app",
    "html_url": "https://github.com/acme/app"
  }
}'

Now sign and send it. This reuses the standard GitHub-style signature header. 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)

Important: for GitHub Actions payloads, set these headers:

X-GitHub-Event: workflow_run
X-GitHub-Delivery: <unique id>

Update the snippet’s endpoint to:

POST /api/v1/webhooks/github-actions/

Expected results

HTTP 202 with a JSON body indicating the event was queued.
Shield logs should show receipt of the delivery id and event type.

Troubleshooting

401 Invalid signature: verify GITHUB_WEBHOOK_SECRET matches what you used to sign.
400 Invalid JSON payload: ensure the request body is valid JSON and sent with Content-Type: application/json.

Verify webhook signatures (HMAC-SHA256)Send pipeline metrics to Shield

Contributing

Introduction

Recipes

Domain Services

Platform Services

Products

Event-Driven Architecture

Testing

Operations

Test the Shield GitHub Actions webhook locally

Prerequisites

1) Confirm the health endpoint

2) Send a signed workflow_run payload

Expected results

Troubleshooting

​Prerequisites

​1) Confirm the health endpoint

​2) Send a signed workflow_run payload

​Expected results

​Troubleshooting

Prerequisites

1) Confirm the health endpoint

2) Send a signed workflow_run payload

Expected results

Troubleshooting