Skip to content
How it worksWhy DetentDashboardInstallDocsVideosOpen source
Docs Operate Detent Mirrored upstream
webhook-freshness.md
Per-project GitHub webhook freshness Available in v0.27.0
Docs source v0.57.0 154392918736 View this file at the pinned commit ↗

GitHub Webhook Freshness

Back to README

Each GitHub-backed project can opt into near-real-time external updates by setting a webhook secret in its WORKFLOW.md:

tracker:
  kind: github
  github_status_source: label
  repository: digitaldrywood/detent
  github_webhook_secret: $DETENT_GITHUB_WEBHOOK_SECRET
polling:
  interval_ms: 60000
  conditional: true

Set DETENT_GITHUB_WEBHOOK_SECRET in the Detent process environment. Configure the repository webhook with:

  • Payload URL: https://<detent-host>/api/v1/webhooks/github
  • Content type: application/json
  • Secret: the same high-entropy value
  • Events: Issues, Pull requests, Check suites, and Labels

Detent verifies X-Hub-Signature-256 with HMAC-SHA256, routes the delivery only to projects whose configured repository and secret match, and queues a fetch for the affected issue. Pull-request and check-suite deliveries resolve Detent's issue from its generated branch name. A repository-level label event has no single issue target, so it queues a normal conditional refresh. Unknown repositories never trigger a fleet-wide fallback. See GitHub's webhook signature validation and event payload reference.

For a ProjectV2 tracker spanning multiple repositories, omit tracker.repository to let the connector verify project membership after signature validation. Set tracker.repository when the project is repository-scoped and strict routing is preferred.

GitHub must be able to reach the payload URL. For local testing, GitHub documents forwarding deliveries with smee.io. For a persistent host without public ingress, an outbound tunnel such as a Cloudflare Tunnel published application can route a public HTTPS hostname to Detent. Configure relays and reverse proxies to preserve the raw request body and GitHub signature headers; modifying either causes signature verification to fail.