Webhooks

ZopDay exposes two webhook endpoints that do not take a session token: one for inbound events from GitHub, and one for the build runner reporting back. Both use cryptographic verification instead, so they can be called without a login.

GitHub Webhook

The GitHub app installed via the GitHub integration delivers events to this endpoint. ZopDay verifies the HMAC signature with the app’s webhook secret, then, for a push, triggers every deployment with auto-deploy on whose repository and branch match.

X-GitHub-Event: push
X-GitHub-Delivery: 72d3162e-cc78-11ed-...
X-Hub-Signature-256: sha256=<hex digest>
Content-Type: application/json

# Pseudocode: ZopDay does this server-side
mac := hmac.New(sha256.New, []byte(webhookSecret))
mac.Write(rawBody)
expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
if !hmac.Equal([]byte(expected), []byte(headerValue)) {
    return 401
}

Duplicate deliveries

Each delivery’s X-GitHub-Delivery ID is remembered. If GitHub redelivers the same event, the request is acknowledged with {"status": "duplicate_delivery"} and nothing runs again: no duplicate builds, no duplicate Helm releases.

Events handled

Build Callback

The GitHub Actions workflow that runs builds on your behalf reports completion back to ZopDay through this endpoint. The request body carries a short-lived callback JWT issued for the revision; the gateway accepts the request without a session token, and ZopDay validates the body token before promoting the revision. This is an internal contract between ZopDay and its build runner.

curl -X POST https://api.zop.dev/build-callbacks/<revisionId> \
  -H "Content-Type: application/json" \
  -d '{
    "callbackJwt": "<callback JWT>",
    "event": "status",
    "status": "succeeded",
    "imageRef": "ghcr.io/acme/checkout:abc1234",
    "commitSha": "abc1234"
  }'

{
  "callbackJwt": "<callback JWT>",
  "event": "status",
  "status": "failed",
  "message": "build step exited with code 1: missing Dockerfile"
}

Token claims

See Builds for how revisions and image references flow through the deploy pipeline, and Deployments for the runtime endpoints that consume the revisions created here.