feat: add docker-hub-webhooks skill

[garethx]

Adds docker-hub-webhooks, a skill for receiving Docker Hub repository webhooks, with Express, Next.js and FastAPI examples (19 tests each).

The scheme: there isn't one

Docker Hub webhooks are unsigned. The webhooks docs describe no signature header, shared secret, HMAC, timestamp or auth option, and the create form takes only a name and a destination URL (255 characters max). The skill therefore ships no verifier. What it does instead:

• Secret URL token in the path (/webhooks/docker-hub/<token>), compared in constant time. It fails closed with 500 when DOCKER_HUB_WEBHOOK_TOKEN is unset. The docs are explicit that this is a bearer secret in a URL and not a Docker signature.
• Repository allowlist (DOCKER_HUB_ALLOWED_REPOS, 403 for anything else), plus shape validation on push_data.tag and repository.repo_name (400 if missing).
• Optional re-check against the Hub API GetRepositoryTag before acting, with a recommendation to pull by digest.

Other mechanics it covers:

• No event type. There is one trigger (a push), and neither the payload nor the headers carry an event, type or action field. Handlers route on repo_name + tag.
• dhi_metadata: pushes to mirrored Docker Hardened Image repos include a map keyed by per-architecture manifest digest (DHI docs, added in dhi: new webhook data docker/docs#26116, Sep 2026).
• callback_url is legacy. The docs say it "is no longer supported". The callback-validation / webhook-chain section (state: success|failure|error) was removed in hub: remove webhook callback_url docker/docs#20565 (Aug 2024), and Add documentation on how to handle the callback_url, and how to verify a callback request came from docker. docker/docs#23955 reports the URL returning 404. The examples ignore the field, and the tests check that no outbound request is made.

Things a reviewer might flag (checked)

• No verifier is deliberate, since Docker Hub doesn't sign anything. The code has no HMAC, no invented X-Docker-Signature header and no IP allowlist.
• Hub API auth: a raw PAT/OAT is not a bearer token. The Hub API reference says each credential must go through POST /v2/auth/token to get a JWT (valid 10 min). The examples exchange the credential and cache the JWT, and send no Authorization header for public repos. I checked on 2026-09-28: GET .../library/repositories/alpine/tags/latest returns 200 with no auth and 401 with an unrecognised bearer.
• Hedged, not asserted: pushed_at is in Unix seconds, inferred from the 10-digit example. Retry policy, timeout and request headers are not documented, and the skill says so rather than giving numbers. The documented example payload dates from 2014, so the skill only relies on a small set of fields.

Cross-checked against hookdeck/core (merged in hookdeck/core#5669)

Core's DOCKER_HUB source type is "No verification (schema only)", uses managed POST, and has external_docs_url = https://docs.docker.com/docker-hub/repos/manage/webhooks/. That matches the primary docs and this skill, with no disagreements. The skill says Hookdeck doesn't verify Docker Hub (there's nothing to verify). It also says Hookdeck's own outbound signature only secures the Hookdeck → destination hop. Docker Hub isn't in the hookdeck.com/docs/sources list yet (checked 2026-09-28).

Testing

• validate-provider.sh docker-hub-webhooks: passes
• Express (Node 22): 19/19 passing
• Next.js (Node 24 / npm 11): 19/19 passing
• FastAPI (fresh venv, Python 3.14): 19/19 passing
• No live account, so there was no end-to-end delivery test.

🤖 Generated with Claude Code