Webhooks
Inbound GitHub webhooks that trigger builds, and outbound webhooks Syntext sends to your endpoints.
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.
You don't set these webhooks up yourself. With the Syntext GitHub App installed, deliveries come through the App. For a repository connected by URL, Syntext creates the repository's push webhook for you when the project is created or its repository changes, using your GitHub connection — and removes it when the project is deleted.
Endpoints
| Endpoint | Purpose |
|---|---|
POST /v1/webhooks/github | Per-repository webhook, created automatically for repos connected by URL |
POST /v1/webhooks/github-app | GitHub App central webhook |
Event Handling
Push events
main) → production buildPull 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
A push:
A pull request adds "preview": true. If no Syntext project is connected to the repository, builds is an empty array.
Signature Verification
Syntext checks GitHub's signature on every delivery to the webhooks it creates. Requests with a missing or invalid signature are rejected with 401:
Comparison is timing-safe.
Debugging Deliveries
Check GitHub's own Recent Deliveries tab under the repository's webhook settings (or the App's advanced settings) for request/response pairs. A 401 Invalid signature usually means the webhook was added or edited by hand — Syntext's own webhook carries the right secret, so remove any hook you added yourself.
Outbound webhooks
Syntext can also notify your systems when something happens in a project. This needs the Webhooks add-on enabled; otherwise these endpoints return 403 addon_disabled. In the dashboard, manage them under Integrations › Webhooks: open a delivery to see what was sent and Replay it, or Rotate secret on an endpoint (the new secret is shown once). Only admins and owners can change endpoints, replay or rotate. Paths are relative to /v1/projects/{projectId}:
| Endpoint | Role | Description |
|---|---|---|
GET /webhook-endpoints | member | List endpoints |
POST /webhook-endpoints | admin | Create an endpoint: { url, events }. The signing secret (whsec_…) is returned once, in this response |
PATCH /webhook-endpoints/{endpointId} | admin | Change url, events or active |
DELETE /webhook-endpoints/{endpointId} | admin | Delete an endpoint |
POST /webhook-endpoints/{endpointId}/test | admin | Send a test event |
POST /webhook-endpoints/{endpointId}/rotate-secret | admin | Replace the signing secret — see Rotate Secret |
GET /webhook-deliveries | member | Recent deliveries and their outcomes — see below |
GET /webhook-deliveries/{deliveryId} | member | One delivery with its payload and request/response bodies — see Get Delivery |
POST /webhook-deliveries/{deliveryId}/replay | admin | Send a past delivery again — see Replay Delivery |
These endpoints need a session JWT (an API key gets 401) and work on any plan. Unlike most of the API, their responses are bare objects — { endpoints }, { endpoint, secret }, { deliveries }, { delivery } — not wrapped in data. A role is checked before the add-on, so a member calling an admin endpoint gets 403 forbidden even when the add-on is off.
Events: build.completed, build.failed, deploy.completed, feedback.submitted, doc_gap.detected, support.handoff (payload). Each delivery is a POST with an X-Syntext-Event header and an X-Syntext-Signature header of the form sha256=<hex>: an HMAC-SHA256 of the raw body, keyed with the endpoint's secret.
Endpoint URL rules
Syntext only delivers to public HTTPS endpoints. A URL is refused with 400 invalid_webhook_url when it isn't https://, when its host doesn't resolve, or when it points at a private or local address (such as localhost or a host on your internal network).
The URL is checked when you create or change an endpoint, and again before every delivery attempt. An endpoint saved before these rules existed, or whose DNS later points somewhere private, shows up as a failed delivery with the reason in the delivery log.
Delivery and retries
2xx response is a success.3xx response is recorded as a failed delivery ("redirects are not followed for webhook deliveries") and is not retried. Point the endpoint at the final URL.4xx responses fail immediately and are not retried.5xx responses and network errors are retried, up to 3 attempts in total, after 1 and then 2 seconds.Listing deliveries
GET /v1/projects/{projectId}/webhook-deliveries returns the 50 most recent deliveries, newest first. Add ?endpointId= to see one endpoint's.
replayOf is the ID of the delivery this one replayed, or null. The list never includes payloads or bodies — fetch one delivery with Get Delivery for those.
What a delivery stores
Each delivery — including test events and replays — keeps enough to inspect and replay it:
payload — the event data as sent. The value of any key whose name contains secret, token, password, passwd, signature, authorization, api_key, private_key, cookie or credential (any case; - works in place of _) is replaced with "[redacted]", at any depth. A payload over 64 KiB after redaction is not kept (null), and that delivery cannot be replayed.requestBody — the JSON envelope that was sent ({ event, timestamp, projectId, data }), with the same redaction, cut at 16 KiB and ending in …[truncated] when longer.responseBody — what your endpoint answered on the last attempt, cut at 16 KiB the same way. Syntext stops reading a longer reply at that point.Request headers, including X-Syntext-Signature, are never stored, and the signing secret is never part of a body. Deliveries recorded before payloads were kept have null in all three fields.
Support handoff event
support.handoff is sent when a reader of your doc site sends their assistant conversation to support from agent mode — see Send to support. It's only sent when Send a support.handoff webhook is on under Integrations › Agentic mode (support.webhook: true) and an active endpoint subscribes to support.handoff.
| Field | Contents |
|---|---|
handoffId | The handoff's ID, as returned by Send to Support |
ticket | The short reference the reader was shown: the first 8 characters of handoffId, upper case |
email | Where to reply to the reader |
summary | The summary as the reader confirmed it |
transcript | The conversation's title and its messages, oldest first, at most 100. Code blocks the reader attached are left out |
memory | What the assistant remembers about the reader. Only present when the reader chose to include it — and only when the project keeps memory and the reader has it on |
For the handoff, the webhook counts as delivered once at least one active endpoint subscribes to support.handoff, whatever that endpoint answers — check the delivery log for failures. With no subscribed endpoint, the webhook doesn't count: if there's no verified support email either, the reader is told their message couldn't be sent.
Testing an arbitrary URL
POST /v1/projects/{projectId}/webhook-test/send sends a signed sample event to any URL you give it, and returns the response. It follows the same rules: the URL must pass the checks above (400 invalid_webhook_url otherwise), and redirects are not followed — a 3xx comes back as the response rather than being chased.
GitLab
For GitLab, trigger builds from CI instead of webhooks — see GitLab CI.