Webhook endpoint — receive GitHub push events

This endpoint is called by GitHub, not by your frontend or CLI. When you create a project in Shipyard, the server registers this URL as a webhook on your GitHub repository via the GitHub API. From that point on, every push to any branch fires a signed HTTP POST to this endpoint. Shipyard verifies the HMAC-SHA256 signature, checks whether the push targets the project’s configured branch, creates a build record, and starts the pipeline.

You do not call this endpoint directly. GitHub sends the request automatically on every push event. The information below is provided so you understand what Shipyard expects and how to troubleshoot delivery failures in GitHub’s webhook settings.

POST /api/webhook

Receives a GitHub push event, verifies the HMAC-SHA256 signature, matches the repository URL and branch to a project, inserts a build record, and starts the build pipeline asynchronously. No JWT auth — authenticated via HMAC-SHA256 signature.

Required headers

Header	Description
`X-Hub-Signature-256`	HMAC-SHA256 signature computed by GitHub using your `WEBHOOK_SECRET`. Format: `sha256=<hex>`. Shipyard computes the same HMAC over the raw request body and compares using a timing-safe equality check.
`X-GitHub-Event`	Event type. Shipyard only processes `push` events. A `ping` event (sent when the webhook is first registered) returns `200` without triggering a build.
`Content-Type`	Must be `application/json`. Set automatically by GitHub when you configure the webhook’s content type as JSON.

Keep your WEBHOOK_SECRET confidential. Anyone who possesses this value can compute a valid signature and send a forged push event to your server, which would trigger arbitrary builds. Rotate the secret in your .env and update the webhook configuration in GitHub if you suspect it has been exposed.

Request body

The request body is the standard GitHub push event payload, sent automatically by GitHub. Shipyard reads the following fields:

string

The HTTPS URL of the repository (e.g., https://github.com/owner/repo). Shipyard uses this to find the matching project in the database.

string

The full Git ref of the pushed branch, in the format refs/heads/<branch>. Shipyard strips the refs/heads/ prefix and compares the result against the project’s configured branch. If they do not match, no build is triggered.

string

The commit message of the most recent commit in the push. Stored as the build’s commit field.

string

The name of the commit author. Stored as the build’s commitAuthor field.

string

The full SHA of the HEAD commit after the push. Stored as the build’s commitHash and used during the clone step to check out the exact revision. Also used as the commit hash if a rollback to this build is requested later.

What Shipyard does with the payload

Verifies the X-Hub-Signature-256 header using HMAC-SHA256 with WEBHOOK_SECRET. Returns 401 if the signature is missing or does not match.
Checks the X-GitHub-Event header. Returns 200 for ping, proceeds for push, and ignores other events.
Strips refs/heads/ from ref to get the branch name.
Queries the database for a project whose repoUrl matches repository.html_url and whose branch matches the extracted branch name. Returns 404 if no match is found.
Inserts a new build record with status: "queued" and responds 201.
Starts the build pipeline asynchronously (clone, Dockerfile generation, Docker build, test run, deploy).

Response

On success (matching project found and build queued):

{
  "message": "Build Queued",
  "build": {
    "id": 14,
    "status": "queued",
    "commit": "fix: update hero copy",
    "branch": "main",
    "commitAuthor": "Jane Doe",
    "commitHash": "a1b2c3d4e5f6",
    "exitCode": null,
    "projectId": 7,
    "startedAt": "2026-04-11T12:00:00.000Z",
    "finishedAt": null
  }
}

Error responses

Status	Condition
`401`	`X-Hub-Signature-256` header is missing
`401`	Signature does not match the computed HMAC — payload may be tampered or `WEBHOOK_SECRET` is wrong
`404`	No project found whose `repoUrl` and `branch` match the push event
`500`	Failed to insert the build record

Troubleshooting webhook deliveries

GitHub logs every webhook delivery attempt, including the request headers, payload, and response code. To inspect failed deliveries:

Go to your repository on GitHub
Open Settings → Webhooks
Click on the Shipyard webhook entry
Scroll to Recent Deliveries to see the response code and body for each delivery

Common reasons for 401 responses:

WEBHOOK_SECRET in your .env does not match the secret stored in GitHub’s webhook configuration. Update one to match the other and redeliver.
The request body was modified in transit (e.g., by a reverse proxy that re-serializes JSON). Shipyard computes the HMAC over the raw body — any reformatting will break the signature.

Common reasons for 404 responses:

The repository URL stored on the project uses HTTPS (https://github.com/owner/repo) but the webhook payload’s repository.html_url differs (e.g., has a trailing .git). Check that the repoUrl recorded in Shipyard matches the format GitHub sends exactly.
The push targeted a branch that is not configured on the project. Only pushes to the branch specified at project creation (or last updated via PUT /api/project/projects/:projectId) trigger a build.

Overview

Endpoints

Webhook endpoint — receive GitHub push events

POST /api/webhook

Required headers

Request body

What Shipyard does with the payload

Response

Error responses

Troubleshooting webhook deliveries

​POST /api/webhook

​Required headers

​Request body

​What Shipyard does with the payload

​Response

​Error responses

​Troubleshooting webhook deliveries

POST /api/webhook

Required headers

Request body

What Shipyard does with the payload

Response

Error responses

Troubleshooting webhook deliveries