Helpdesk Git Webhook Tracking

The Helpdesk module can ingest signed Git push webhooks and automatically link commits to tickets when commit messages, branch names, or commit URLs contain a ticket reference such as HD-2026-00012.

1. Register the repository

Open the Helpdesk settings page:

/helpdesk/settings

In the Git section, create a repository with:

Field	Value
Provider	`github`, `gitlab`, or `git`
Remote URL	Your repository remote URL
Default branch	Usually `develop` or `main`
Webhook secret	A strong random secret, for example `openssl rand -hex 32`

After saving, the repository table shows the webhook endpoint:

/api/helpdesk/git/webhook/{repository_id}

2. Ticket reference convention

Use the Helpdesk ticket reference in branch names and commit messages:

git checkout -b feature/HD-2026-00012-canned-responses
git commit -m "HD-2026-00012 Add canned response macro rendering"

The parser recognises this format:

HD-YYYY-00000

The first matching reference is linked to the stored commit when the ticket exists and matches the repository company/project scope.

3. GitHub setup

In GitHub, open the repository settings and add a webhook:

GitHub field	Value
Payload URL	`https://your-app.test/api/helpdesk/git/webhook/{repository_id}`
Content type	`application/json`
Secret	Same value stored in Helpdesk
Events	Push events

The module validates X-Hub-Signature-256 using HMAC SHA-256 and rejects unsigned or invalid requests.

4. GitLab setup

In GitLab, open Settings > Webhooks and add:

GitLab field	Value
URL	`https://your-app.test/api/helpdesk/git/webhook/{repository_id}`
Secret token	Same value stored in Helpdesk
Trigger	Push events

The module validates X-Gitlab-Token and rejects invalid requests.

5. Generic Git provider setup

For a simple internal provider, send a JSON push payload to the same endpoint with:

X-Helpdesk-Token: your-secret
X-Helpdesk-Event: push

The payload should include:

{
  "ref": "refs/heads/develop",
  "commits": [
    {
      "id": "full-commit-hash",
      "message": "HD-2026-00012 Fix ticket workflow",
      "url": "https://example.test/commit/full-commit-hash",
      "timestamp": "2026-06-15T10:00:00+00:00",
      "author": {
        "name": "Support Agent",
        "email": "agent@example.com"
      }
    }
  ]
}

6. Audit trail

Every accepted, ignored, or rejected webhook delivery is recorded in:

helpdesk_git_webhook_logs

Stored data includes provider, event, delivery id, status, message, commit count, linked count, ignored count, payload, and received timestamp.

7. Verification commands

Run the focused feature test after installing the updated module:

php artisan test Modules/Helpdesk/Tests/Feature/GitWebhookIngestionTest.php

Then run the full Helpdesk test set:

php artisan test Modules/Helpdesk/Tests/Feature Modules/Helpdesk/Tests/Unit
php artisan dusk Modules/Helpdesk/Tests/Browser

3.1 KiB Raw Blame History