GitHub webhook

This page covers how Docup receives push notifications from GitHub, including endpoint configuration, signature verification, de-duplication, and event behaviors. You do not configure this when you use the hosted Docup. This page explains what happens behind the Updates on push behavior, and is useful if you run your own copy of Docup. See Local setup.

Endpoint#

POST /api/webhooks/github

Set it as the webhook URL of your GitHub App, with the same secret as GITHUB_WEBHOOK_SECRET, and subscribe the app to the push event. The installation event is also handled.

Verification#

Every request must carry an X-Hub-Signature-256 header. Docup computes an HMAC-SHA256 of the raw request body with the webhook secret and compares it with the header in constant time. A missing, malformed or wrong signature returns 401 Bad signature.

De-duplication#

GitHub sometimes sends a delivery again. Docup stores each X-GitHub-Delivery id in Redis for 24 hours and answers 200 Already handled to repeats. If handling fails, the id is removed, so Redeliver in the GitHub app settings works. If Redis cannot be reached, the delivery is handled anyway, because an update that runs twice finds nothing new the second time.

Events#

Responses#

The endpoint answers quickly, since GitHub gives up after ten seconds. The update itself runs in the background.

What an update does with a push#

The task is started with a debounce: pushes less than a minute apart become one update, at most ten minutes after the first, and one project's updates run one after another. Starting the task throws if the background service cannot be reached, so GitHub sees the delivery fail and can send it again. See Keeping docs up to date for what the update does.

Update execution limits#

The background update task processes changed files and rewrites pages under these exact limits: