Webhook Endpoint Architecture#

Dokploy exposes three webhook handler endpoints under apps/dokploy/pages/api/deploy/ 1:

These two patterns are architecturally opposite:

• GitHub: one shared URL for every application in a GitHub App installation — the endpoint identifies which applications to deploy via database queries.
• RefreshToken: a unique URL per application/compose — the token in the URL directly addresses a single record.

GitHub: Single Shared Endpoint#

Every GitHub App installation registers the same callback URL, <host>/api/deploy/github, during provider setup 2. All push and pull_request events from that installation land here regardless of which repository or application is involved.

Request validation flow 3:

1. Reject if x-hub-signature-256 header is missing.
2. Look up the GitHub provider record by installation.id from the payload body.
3. Verify the HMAC-SHA-256 signature against that provider's githubWebhookSecret.

Application matching is done with broad db.query.applications.findMany() calls filtered at the DB level — never narrowed by any token in the URL itself 4:

• push + branch events: filter by sourceType=github, autoDeploy=true, triggerType=push, branch, repository, owner, githubId.
• push + tag events: same filters but triggerType=tag 5.
• pull_request events (preview deployments): filter by sourceType=github, repository, branch, isPreviewDeploymentsActive=true, owner, githubId 6.

One webhook event can therefore trigger deployments for multiple applications in a single request 7.

Cross-Application Conflict Implications#

Because the GitHub endpoint matches all applications that share the same GitHub provider and repository/branch combination, a single push can trigger simultaneous deploys across unrelated Dokploy applications. The key implications:

• Fan-out by design: a push to main on repo acme/api will trigger every application in that installation that is configured for acme/api@main with autoDeploy=true. There is no per-application filter key in the webhook URL.
• watchPaths as a narrowing filter: the shouldDeploy() helper 8 gates each application independently on its configured glob patterns before enqueuing. This is the only per-application opt-out for push events.
• No webhook secret per application: validation happens at the provider level (one secret per GitHub App installation), not per application. A compromised provider secret exposes all applications under that installation.
• Preview deployment conflict surface: for pull_request events, every matching application fires a preview build. Label filters (previewLabels) and collaborator permission checks (previewRequireCollaboratorPermissions) are the per-application gates 9.

RefreshToken Pattern (Non-GitHub Providers)#

For GitLab, Bitbucket, Gitea, and Docker registry webhooks, each application gets a unique webhook URL (/api/deploy/<refreshToken>). The handler fetches the single application record matching that token and rejects immediately if none is found 10. The provider type is detected at runtime from request headers (x-gitlab-event, x-event-key, x-gitea-event).

This means a non-GitHub webhook event is inherently scoped to one application — no fan-out, no cross-application ambiguity.

Key Source Files#