/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog

Webhooks

Inbound GitHub webhooks that trigger builds, and outbound webhooks Syntext sends to your endpoints.

7 min read

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.

Note

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

EndpointPurpose
POST /v1/webhooks/githubPer-repository webhook, created automatically for repos connected by URL
POST /v1/webhooks/github-appGitHub App central webhook

Event Handling

Push events

•
Pushes to the project's configured branch (default main) → production build
•
Pushes to other branches are ignored — open a pull request to get a 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

A push:

json
{
"data": {
"builds": ["b2f1c3d4-…"]
}
}

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:

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

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}:

EndpointRoleDescription
GET /webhook-endpointsmemberList endpoints
POST /webhook-endpointsadminCreate an endpoint: { url, events }. The signing secret (whsec_…) is returned once, in this response
PATCH /webhook-endpoints/{endpointId}adminChange url, events or active
DELETE /webhook-endpoints/{endpointId}adminDelete an endpoint
POST /webhook-endpoints/{endpointId}/testadminSend a test event
POST /webhook-endpoints/{endpointId}/rotate-secretadminReplace the signing secret — see Rotate Secret
GET /webhook-deliveriesmemberRecent deliveries and their outcomes — see below
GET /webhook-deliveries/{deliveryId}memberOne delivery with its payload and request/response bodies — see Get Delivery
POST /webhook-deliveries/{deliveryId}/replayadminSend 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).

json
{
"error": {
"code": "invalid_webhook_url",
"message": "Webhook URL resolves to a private or reserved address",
"details": { "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}

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

•
Each attempt times out after 5 seconds.
•
A 2xx response is a success.
•
Redirects are not followed. A 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.
•
Other 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.

json
{
"deliveries": [
{
"id": "9d4e2b7a-6c1f-4a3e-8b5d-0f2a7c9e1b34",
"endpointId": "2c7f1e9a-4b3d-4e8f-9a6c-1d0e5b7a3f28",
"projectId": "3f6c1d2e-8a4b-4f7e-9c21-5b0d7e6a9f13",
"event": "build.completed",
"statusCode": 200,
"success": true,
"durationMs": 184,
"error": null,
"replayOf": null,
"createdAt": "2026-11-08T10:15:02.000Z"
}
]
}

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.

json
{
"event": "support.handoff",
"timestamp": "2026-11-13T15:20:07.412Z",
"projectId": "3f6c1d2e-8a4b-4f7e-9c21-5b0d7e6a9f13",
"data": {
"projectId": "3f6c1d2e-8a4b-4f7e-9c21-5b0d7e6a9f13",
"handoffId": "4a7c2e19-8b3d-4f6a-9c05-e1d2b3a4c5f6",
"ticket": "4A7C2E19",
"email": "dana@example.com",
"summary": "I added the CNAME for my apex domain but verification still fails after a day.",
"transcript": {
"title": "Adding a custom domain",
"messages": [
{ "role": "user", "content": "How do I add a custom domain?" },
{ "role": "assistant", "content": "Add the domain under **Settings › Domains** [guides/custom-domains#Add a domain]…" }
]
},
"memory": ["Hosts DNS on Cloudflare"]
}
}
FieldContents
handoffIdThe handoff's ID, as returned by Send to Support
ticketThe short reference the reader was shown: the first 8 characters of handoffId, upper case
emailWhere to reply to the reader
summaryThe summary as the reader confirmed it
transcriptThe conversation's title and its messages, oldest first, at most 100. Code blocks the reader attached are left out
memoryWhat 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.

Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext