Deployment Webhooks

Get notified when your live documentation finishes deploying, using a GitHub or GitLab push webhook and the Deployments API.

Overview

Deployment webhooks let your own systems react when your documentation goes live: post to Slack, purge a CDN cache, run link checks, or unblock a release pipeline.

Documentation.AI deploys your live site whenever a commit lands on your deployment branch (usually main). A deployment webhook follows that commit through to the finished deployment:

Your Git provider sends a push event to your endpoint when the deployment branch changes.
Your endpoint finds the deployment that the push started, using the Deployments API.
Your endpoint polls that deployment until it is ready, error, or cancelled, then runs your own logic.

Every commit on the deployment branch reaches your endpoint, whether it came from a direct push, a merged pull request, or a publish from the web editor.

Before you start

A documentation project connected to GitHub or GitLab
A Documentation.AI plan with REST API access (Standard or above)
An API key from Settings → API Keys. A Viewer key is enough, because the endpoint only reads deployments. See Getting Your API Key.
Permission to add webhooks to the repository: admin on GitHub, Maintainer on GitLab
An HTTPS endpoint that your Git provider can reach

Set up the webhook

Generate a random secret first. You'll give the same value to your Git provider and to your endpoint, so the endpoint can reject requests that don't come from your repository.

openssl rand -hex 32

Open webhook settings

In your repository, go to Settings → Webhooks and click Add webhook.

Point it at your endpoint

Payload URL: your endpoint, for example https://hooks.example.com/webhooks/docs
Content type: application/json
Secret: the secret you generated

Choose the push event

Select Just the push event, keep Active checked, and click Add webhook.

GitHub sends push events for every branch. Your endpoint ignores all but the deployment branch.

Use a webhook you create yourself, as shown here. Don't edit or reuse the webhook Documentation.AI registers on your repository, which it needs to deploy your site.

Handle the push event

When the push event arrives, your endpoint follows the deployment it started.

Verify the request

Reject requests that don't carry your secret. GitHub signs the body in the X-Hub-Signature-256 header, and GitLab sends the secret as-is in the X-Gitlab-Token header.

Check the branch

Continue only when ref in the payload is your deployment branch, such as refs/heads/main. On GitHub, this is where pushes to other branches are ignored.

Respond right away

Return a 2xx response straight away and do the rest in the background. Git providers stop waiting after about 10 seconds, and a deployment takes longer.

Find the deployment

Call GET /deployments. Deployments come back newest first. Pick the first one where isPreview is false, branch is your deployment branch, and createdAt is no more than a minute before the push event arrived.

curl "https://api.documentationai.app/api/v1/deployments?limit=10" \
  -H "Authorization: Bearer dai_your_api_key"

Documentation.AI receives the same push, so the deployment can appear slightly before or after your event arrives. If there's no match yet, try again every few seconds for up to a minute.

Poll until it finishes

Call GET /deployments/{deploymentId} every 10 seconds or so until status is ready, error, or cancelled.

curl https://api.documentationai.app/api/v1/deployments/9f1c2e64-3b47-4a8d-91f5-7c2e0a6d5b31 \
  -H "Authorization: Bearer dai_your_api_key"

Run your own logic

Once the deployment is finished, notify your team, purge caches, or continue your release pipeline.

Run the endpoint somewhere that can keep working after it responds, such as a container, a VM, or a background job queue. Most serverless functions stop when the response is sent or after a few seconds, which ends the polling before the deployment finishes.

The finished deployment

A finished deployment from GET /deployments/{deploymentId} looks like this:

{
  "deploymentId": "9f1c2e64-3b47-4a8d-91f5-7c2e0a6d5b31",
  "status": "ready",
  "url": "https://docs.acme.com",
  "branch": "main",
  "isPreview": false,
  "triggerType": "auto",
  "logs": null,
  "createdAt": "2026-09-18T10:04:12.000Z",
  "updatedAt": "2026-09-18T10:06:47.000Z"
}

Field	Description
`status`	`ready` when the site is live, `error` when the build failed, `cancelled` when it was stopped
`url`	Where the documentation is published
`branch`	The branch that was deployed
`logs`	Why the deployment failed, when `status` is `error`
`createdAt` / `updatedAt`	When the deployment started and when it last changed. For a finished deployment, `updatedAt` is when it finished.

Polling and rate limits

Every request counts against your API key's per-minute limit. Polling every 10 seconds makes about six requests a minute while a deployment builds, which fits comfortably in most limits. If you poll more often, or share the key with other scripts, watch the x-ratelimit-remaining header and back off on 429 responses. See Rate Limiting.

Redeploys without a commit

A redeploy started with POST /deploy doesn't create a commit, so no push event reaches your endpoint. POST /deploy returns the deploymentId directly, so the script that started the redeploy can poll it without the lookup step.

Troubleshooting

Was this page helpful?