---
title: "Webhook"
manual: "How to Document"
version: "main"
permalink: "https://docs.typo3.org/permalink/h2document:webhook"
source: "Howto/WritingDocForExtension/Webhook.rst"
modified: "2026-09-14T09:38:54+00:00"
---

# Webhook

This section explains how to configure webhooks for automatic documentation
rendering in a repository.

TYPO3 documentation rendering supports Git as a Version Control System (VCS)
and integrates with the following repository hosts:

-   [GitHub](https://docs.typo3.org/permalink/h2document:webhook-github)
-   [Bitbucket cloud](https://docs.typo3.org/permalink/h2document:webhook-bitbucket-cloud) and Bitbucket self-hosted
-   [GitLab Cloud](https://docs.typo3.org/permalink/h2document:webhook-gitlab) and [GitLab self-hosted](https://docs.typo3.org/permalink/h2document:webhook-gitlab)

**Table of Contents**

-   [Approval](https://docs.typo3.org/permalink/h2document:approval)
-   [Foreign setups](https://docs.typo3.org/permalink/h2document:foreign-setups-1)
-   [How webhooks work](https://docs.typo3.org/permalink/h2document:how-webhooks-work)
-   [Legacy webhook](https://docs.typo3.org/permalink/h2document:legacy-webhook)
-   [GitHub](https://docs.typo3.org/permalink/h2document:github)
-   [Bitbucket cloud](https://docs.typo3.org/permalink/h2document:bitbucket-cloud)
-   [GitLab cloud and Self-Hosted](https://docs.typo3.org/permalink/h2document:gitlab-cloud-and-self-hosted)
-   [Reading the webhook deliveries on GitHub](https://docs.typo3.org/permalink/h2document:reading-the-webhook-deliveries-on-github)
-   [Testing webhooks](https://docs.typo3.org/permalink/h2document:testing-webhooks)

## Approval

Before your documentation is rendered, the TYPO3 Documentation Team must approve
the repository the first time you request rendering.

For approval, ensure the following:

1.  The extension must be published in the TYPO3 Extension Repository (TER)
    under the same extension key specified
    in [composer.json](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/ComposerJson.html#composer-json).
1.  The Git repository should be referenced on the TER detail view page.

These steps help prevent misuse of the infrastructure and ensure extension
name consistency.

If the approval process takes too long, request approval via the Slack channel
[#typo3-documentation](https://typo3.slack.com/messages/C028JEPJL). Register
for Slack at [my.typo3.org](https://my.typo3.org/index.php?id=35).

## Foreign setups

If your repository is hosted outside the supported platforms
(GitHub, GitLab, Bitbucket) or its structure differs from a typical TYPO3
extension, you must create a mirror on a supported platform. Otherwise,
automatic rendering will not be possible.

## How webhooks work

If you are new to webhooks, refer to
the [GitHub Webhooks Guide](https://developer.github.com/webhooks/).

The webhook setup described below ensures that rendering is triggered only on
push events.

To test the webhook integration, push changes to
the `main` or `documentation-draft` branch (see [Supported branches](https://docs.typo3.org/permalink/h2document:migrate-branches)).

> [!NOTE]
> Documentation rendering is triggered only for the version affected by the
> push event, not the entire repository. For example, a push event on
> branch `13.4` will render only that version.

## Legacy webhook

If a webhook was previously configured, it may be using a deprecated method.
A compatibility layer is still in place but will be removed in the future.

## GitHub

To enable automatic documentation rendering using GitHub webhooks, follow
these steps:

1.  Navigate to the repositories **Settings** tab.

    ![](../../_Images/webhook/github/repository-start.png)
1.  Open the **Webhooks** section.

    ![](../../_Images/webhook/github/settings-tab.png)
1.  Click **Add webhook**.

    ![](../../_Images/webhook/github/webhook-section.png)
1.  Configure the webhook settings:

    -   **Payload URL**: `https://docs-hook.typo3.org`
    -   **Content type**: `application/json`
    -   **SSL verification**: Enabled
    -   **Events**: `Just the push event`
    -   **Active**: Checked

    Click **Add webhook**.

    ![](../../_Images/webhook/github/webhook-add.png)
1.  Verify webhook creation.

    GitHub will confirm that the webhook was successfully added.

    ![](../../_Images/webhook/github/webhook-added.png)
1.  Test the webhook.

    Visit [intercept.typo3.com](https://intercept.typo3.com/admin/docs/deployments)
    and check the **Recent actions** section. Push a commit
    to `main` or `documentation-draft` to trigger the webhook.

    ![](../../_Images/webhook/github/intercept-feedback.png)

## Bitbucket cloud

To configure a webhook for a Bitbucket repository:

1.  Open the repository **Settings**.

    ![](../../_Images/webhook/bitbucket/cloud/repository-start.png)
1.  Go to the **Webhooks** section.

    ![](../../_Images/webhook/bitbucket/cloud/settings-tab.png)
1.  Click **Add webhook**.

    ![](../../_Images/webhook/bitbucket/cloud/webhook-section.png)
1.  Configure the webhook:

    -   **Title**: `TYPO3 Docs`
    -   **URL**: `https://docs-hook.typo3.org`
    -   **Active**: Checked
    -   **Triggers**: `Repository push`

    Click **Save**.

    ![](../../_Images/webhook/bitbucket/cloud/webhook-add.png)
1.  Verify webhook creation.

    Bitbucket will confirm webhook addition.

    ![](../../_Images/webhook/bitbucket/cloud/webhook-added.png)
1.  Test the webhook.

    Visit [intercept.typo3.com](https://intercept.typo3.com/admin/docs/deployments)
    and check **Recent actions**. Push a commit
    to `main` or `documentation-draft` to trigger the webhook.

    ![](../../_Images/webhook/bitbucket/cloud/intercept-feedback.png)

## GitLab cloud and Self-Hosted

To set up a GitLab webhook:

1.  Open the **Integrations** section of the repository.

    ![](../../_Images/webhook/gitlab/repository-start.png)
1.  Add a webhook with the following settings:

    -   **URL**: `https://docs-hook.typo3.org`
    -   **Triggers**: `Push events` and `Tag push events`

    Click **Add webhook**.

    ![](../../_Images/webhook/gitlab/webhook-add.png)
1.  Verify webhook creation.

    The webhook will appear in the list.

    ![](../../_Images/webhook/gitlab/webhook-added.png)
1.  Test the webhook.

    Visit [intercept.typo3.com](https://intercept.typo3.com/admin/docs/deployments)
    and check **Recent actions**. Push a commit
    to `main` or `documentation-draft` to trigger the webhook.

    ![](../../_Images/webhook/gitlab/intercept-feedback.png)

## Reading the webhook deliveries on GitHub

In the GitHub repository settings under **Webhooks > Recent
Deliveries** every delivery shows the response of the documentation server:

-   `200`: ping accepted.
-   `204`: push accepted, a rendering was triggered.
-   `412`: repository not approved yet — expected for the first test
    delivery before the Documentation Team has approved the project.

A branch push and a tag push are separate deliveries. When a new version does
not appear on docs.typo3.org, check the delivery of the **tag** push — the
branch push having succeeded says nothing about the tag. GitLab and Bitbucket
show the corresponding information in their webhook edit views.

## Testing webhooks

To test webhook configurations before integrating with TYPO3, use:

-   [Beeceptor](https://beeceptor.com/) for quick API testing.
-   [Webhook.site](https://webhook.site/) to inspect webhook payloads in real-time.

These tools help debug webhook calls and ensure correct configuration before enabling documentation rendering.