Webhooks

Syntext receives webhooks from your git provider to trigger builds automatically — production builds on pushes to your configured branch, and preview builds for pull requests.

If you installed the Syntext GitHub App, webhooks are configured automatically and you can skip this page. Manual setup is only needed for repos connected by URL.

Endpoints

Endpoint	Purpose
`POST /v1/webhooks/github`	Per-repo webhook (manual setup)
`POST /v1/webhooks/github-app`	GitHub App central webhook (automatic)

Manual GitHub Setup

In your repo: Settings → Webhooks → Add webhook

Payload URL: https://api.syntext.dev/v1/webhooks/github
Content type: application/json
Secret: a shared secret (also configured on your Syntext project)
Events: push and pull_request

Every push to your configured branch triggers a production build. Pushes to other branches trigger preview builds.

Event Handling

Push events

Pushes to the project's configured branch (default main) → production build
Pushes to other branches → preview build
Changed file paths from the commits are recorded on the build for incremental processing

Pull request events

PRs with action opened, synchronize, or reopened trigger a preview build of the PR's head commit. Other PR actions are ignored.

Response

{
  "data": {
    "builds": ["bld_abc123"],
    "preview": true
  }
}

If no Syntext project is connected to the repository, builds is an empty array.

Signature Verification

Syntext verifies the X-Hub-Signature-256 header on every delivery using HMAC-SHA256 with your webhook secret. Requests with a missing or invalid signature are rejected with 401:

{
  "error": { "code": "unauthorized", "message": "Invalid signature" }
}

Comparison is timing-safe. There is nothing to configure client-side — GitHub signs deliveries automatically once the secret is set.

Debugging Deliveries

Recent webhook deliveries and their outcomes are visible per project:

GET /v1/projects/{projectId}/webhook-test/deliveries

Requires authentication. Also check GitHub's own Recent Deliveries tab under the webhook settings for request/response pairs.

A 401 Invalid signature response almost always means the secret configured in GitHub doesn't match the one on the Syntext project.

GitLab

For GitLab, trigger builds from CI instead of webhooks — see GitLab CI.