Hammerhead API integration
The Karoo on your user’s handlebars, behind the same connect call as every watch we support. They authorise once on a screen we host, and finished rides arrive as FIT files.
From 32.50 € a month billed annually, no per-athlete fee, 30 days to change your mind.
link a hammerhead athlete — no hammerhead credential involved
// Your own id for your own user. You hold no hammerhead client secret.
const link = await stridee.post('/v1/connect', {
provider: 'hammerhead',
external_user_id: 'user_4821',
return_uri: 'https://app.yourapp.com/settings/devices',
});
// Redirect their browser. Good for 30 minutes.
res.redirect(link.connect_url);A Hammerhead workout finishes. An activity.created event carrying Hammerhead’s own summary, sealed to your public key.
- Sport as Hammerhead classified it — road, gravel, MTB, e-bike — mapped onto one vocabulary
- Start time and Hammerhead’s own activity id for the ride
- The FIT file the Karoo recorded, fetched and stored before you are told about it
- The device as “Hammerhead” — the API does not say which Karoo it was
The Hammerhead integration you’re not writing. The registration, the consent screen and the token refresh are ours.
First, notice there are two hosts
Authorisation lives under /v1/auth and everything else under /v1/api, and the spec expresses that as a per-operation override of a single servers block. Miss it and every call after the token exchange 404s while your bearer token is perfectly valid — which reads as an auth bug and is not one. It is an afternoon of the wrong debugging.
Then handle a webhook that will not be resent
The delivery is two ids and nothing else — no summary, no sport, no file URL — and Hammerhead’s own spec says of the response: “Hopefully successful, errors are ignored.” There is no retry ladder behind that. A delivery you drop while your database is failing over is a ride your user never sees again, so the acknowledge has to be instant and the work has to happen somewhere it can fail safely.
And guess how the signature is encoded
Every delivery is signed with HMAC-SHA256 over the raw body in an X-Hmac-Signature header. The docs give you the algorithm and the key and never say whether the digest is hex or base64 — and picking wrong presents as every webhook being silently dropped with a correct secret in your config, which is close to the worst way for an integration to fail.
And know what deauthorise actually does
Hammerhead’s deauthorise endpoint does not just drop a token: it removes the account link and deletes every route and workout your app imported for that rider. It is scoped to a client id, so on a shared integration one user’s disconnect can take another product’s content with it. Working out which calls are safe to make on whose behalf is the kind of thing you find out afterwards.
All of it is one POST /v1/connect naming hammerhead, and a webhook handler you write once for every provider.
Connect a devicelink a hammerhead athlete — no hammerhead credential involved
// Your own id for your own user. You hold no hammerhead client secret.
const link = await stridee.post('/v1/connect', {
provider: 'hammerhead',
external_user_id: 'user_4821',
return_uri: 'https://app.yourapp.com/settings/devices',
});
// Redirect their browser. Good for 30 minutes.
res.redirect(link.connect_url);What Hammerhead covers. Nothing is marked live unless an endpoint serves it today.
- ConnectLive today
- ActivitiesLive today
- WellnessThe provider doesn’t expose it
- Workout pushDesigned, not yet shipped
Every Hammerhead device. The link is with the athlete’s account, not a watch, so models released after you ship reach you unchanged.
Current
- Karoo (2024)
Previous generations
- Karoo 2
- Karoo 1
Two weeks free. Then from 32.50 € a month.
Checkout is the signup. No waitlist, no sales call.
- Garmin, COROS, Polar, Wahoo, Zepp, Hammerhead and Fitbit behind one connect call
- Every endpoint on every plan — never priced per athlete
- 14 days free, and no card charged until they are up
- 30-day money-back guarantee
Cancel any time from the Stripe billing portal, or email [email protected] within 30 days and we refund you.
Plans start at
Or 39 €/month, month to month. Paying annually gets you two months free.
Hacker, Startup, Scale and Enterprise differ on one thing: how many of your users may connect a watch. Everything else is on every plan.
See the plans14-day free trial · cancel any time
We create the account on the email you pay with, automatically. Sign in at platform.stridee.com/login. Nothing to wait for.
Hammerhead API questions
No. That is the point of the integration. We hold the Hammerhead Developer API registration, the client credentials and the redirect URI; you call POST /v1/connect with your own id for your own user and redirect their browser to the URL that comes back. There is no Hammerhead secret in your environment, no callback route in your router, and no approval queue between you and your first connected athlete.
Two weeks free, then from 32.50 € a month billed annually — or 39 € a month with no year to commit to — for the whole API, every provider and every endpoint, with no per-athlete metering. Plans differ on one thing: how many of your users may connect a watch. Hacker is 250, for a project and its first users; Startup covers up to 5,000 of them; Scale up to 250,000; Enterprise removes the ceiling; and none of them meters calls, activities or endpoints. The usual price for a unified wearable API starts in the hundreds of dollars a month and charges again for each connected user, which is a pricing model that punishes exactly the thing you are trying to do. There is a 30-day money-back guarantee on any charge, and cancelling is a button in the Stripe billing portal; access ends when the period does.
You get push, not polling. When an athlete finishes a workout, Hammerhead notifies us and we send you an activity.created delivery — sealed to your public key as a JWE and signed with a detached JWS you verify against our published JWKS. Latency is whatever Hammerhead takes to process the upload from the watch, which is theirs to own and typically a matter of minutes. You never write a polling loop and never hold a rate-limit budget.
There is no API key anywhere in this, in either direction. You authenticate to us with an Ed25519 signature over the request itself — RFC 9421 HTTP Message Signatures — using a private key that never leaves your machine, so there is no bearer token sitting in a log line, a CI variable or a backup. And we never hand you the provider's own credentials either.
All of them, because the integration is with the Hammerhead account rather than with a head unit. Anything that syncs into a rider’s Hammerhead account reaches you — the 2024 Karoo, the Karoo 2 and the original — and a model released next year works on the day it ships without a change on either side. The one thing to know is that the API does not tell us which unit recorded a ride, so the device on an activity.created delivery reads “Hammerhead” rather than a model name.
No, and not eventually either. A Karoo is a bike computer bolted to a stem and switched off between rides — there is no wrist, so there is no resting heart rate, no sleep and no step count to read. Every other provider on this site is a watch and this one is not, which is why the coverage table above marks daily summaries as unavailable rather than planned. If you need wellness data from these riders, it has to come from a watch they also wear.
Not yet. Hammerhead publishes the surfaces for both — a route push and a workout push — and we have built neither, so a call naming this provider on those endpoints comes back as a 422 rather than half-working. Activities are what is live today. It is the reason the table above marks workout push as planned for Hammerhead while it is live on Garmin, COROS and Wahoo.
Not today. Hammerhead does publish a paginated history endpoint, so this is a matter of code rather than of what the API allows, but nothing replays past rides into your webhook at the moment a rider consents — you start receiving activities from their next ride. If backfill matters for your product, say so and it moves up the list; we would rather tell you it is missing than have you discover it on your first real user.
Hammerhead lets an athlete grant a subset of what was requested, and — unusually — the token response never says which subset they chose. So we do not record a guess. If the grant turns out not to cover reading activities, the first fetch comes back refused, the connection moves to reauth_required, and you get an account.reauth_required event telling you to ask them to reconnect. That is the same event and the same handling as an expired credential on any other provider.
The full documentation is public and needs no account. Still have questions? Ask us in Discord
Ask us in DiscordOne integration, not seven. Same connect call, same event shape, same plan. Your second provider is a string change.
