Connect a repository

Two things have to be true before commits turn into entries: the provider must deliver pushes to your webhook URL, and the repository must be attached to a project. Miss the second and the deliveries arrive with nowhere to go.

Subscribe to the pull request events as well and the same webhook feeds the delivery metrics — how long reviews take, what is open, what has gone stale. None of that can be recovered from pushes: opening a pull request pushes nothing at all, and a merge names it only in the commit message, or not even there after a rebase merge.

Get your webhook URL

The URL is unique to you. It is also on Settings → Git webhook.

Create a secret

Every delivery is signed, and Clocktopus rejects anything that fails the check — GitHub signs with SHA-256, Bitbucket with an HMAC. Create a secret here and paste the same value into the provider.

The secret is shown once. If you lose it, create another and update the provider.

GitHub

Go to Settings → Webhooks → Add webhook, on either the repository or the organisation.

Field	Value
Payload URL	Your webhook URL from above
Content type	application/json
Secret	The secret you just created
Events	Let me select individual events → Pushes, Pull requests, Pull request reviews
Active	Checked

Save with Add webhook. GitHub immediately sends a ping to confirm the endpoint is reachable.

Which event powers what

Pushes alone is enough for time tracking, and is what an existing webhook is probably set to — GitHub subscribes to it by default. The other two are what fill the delivery metrics, and they are not interchangeable:

Event	What it makes possible
Pushes	Time entries, commit counts, and the effort behind every other figure
Pull requests	Open / stale / merged / abandoned, cycle time, merge rate, work complexity
Pull request reviews	Review rate, time to first review, and review cycles — nothing else does

Leave Pull request reviews off and everything else still works, but review timing disappears entirely and the review rate undercounts: without it the only review Clocktopus can still see is a pull request merged by somebody other than its author.

application/x-www-form-urlencoded also works, so an existing webhook set that way keeps running. GitHub's own webhook documentation covers the screen in more detail.

Bitbucket

Go to Repository settings → Webhooks → Add webhook, or the same path under workspace settings.

Field	Value
URL	Your webhook URL from above
Secret	The secret you just created
Triggers	Repository push; under Pull request: Created, Updated, Merged, Declined, and — for review tracking — Approved, Changes requested, Comment created
Status	Active

Approved, Changes requested and Comment created are Bitbucket's review triggers — the equivalent of GitHub's Pull request reviews. Without them the review rate and review cycles stay empty.

Bitbucket sends no diff statistics on pull request events, so pull request size stays blank for Bitbucket repositories. Everything else — timings, states, review turnaround — works the same as GitHub.

Save with Save or Create webhook. Atlassian's webhook documentation covers the screen in more detail.

Attach the repository to a project

In Settings → Projects, open the project and add the repository URL.

Commits are only tracked for repositories listed on a project. This is also what gives agent spend somewhere to land — an agent running in an unattached repository is recorded, but lands in the unattributed row rather than against a client.

Do not attach the same repository to two projects. Nothing is guessed when several projects claim one repository, because a wrong guess bills the wrong client.

A delivery only ever books to your own project

The webhook URL is per account, and it decides where the time lands. A delivery resolves the repository against your projects, and only then works out which teammates to credit — so a push to your URL can never create entries in an account that did not install it, whoever wrote the commits.

Two unrelated accounts can therefore track the same repository without interfering: each adds their own webhook and maps the repository in their own project. A repository accepts many webhooks, so nothing has to be shared.

Within one team the opposite is true, and deliberately: one webhook is enough. Every teammate who can access the project is credited for their own commits from the same delivery.

Make sure your commits are yours

Git stamps commits with the email in your local config, not the one you sign in with:

git config user.email

If it differs from your Clocktopus login, add it under tracked emails. The address also has to belong to someone who can access the project the repository is attached to — a commit written by an outside address is reported to you as untracked rather than credited to a stranger.

Check it worked

Push something, then look at Settings → Git webhook for recent deliveries. Two failures account for nearly all of them:

• Invalid signature — the secret in the provider does not match the one in Clocktopus, or the repository URL on the project does not match the repository actually sending.
• Delivered, but no entry — the repository is not attached to a project, or the commit author email is not tracked.