feat: add 57 doc-sourced samples for aftership, circleci, docker-hub, grafana, snipcart, sparkpost + checkout Identity Verification

[garethx]

The sample-payload stage of the add-a-source pipeline for nine newly registered providers. The registry rows are on hookdeck/webhook-registry main at fdbef66, and the samples come from that commit's samples-doc/.

57 doc-sourced samples. 140 → 146 providers. No existing file changed. git status shows 6 new provider directories and 22 new files under providers/checkout/1.0.25/, and nothing else.

provider	added	version dir	topic_identifier
aftership	1	2026-07/	event
circleci	2	latest/	circleci-event-type (header)
docker-hub	1	latest/	none
grafana	1	latest/	status
snipcart	3	latest/	eventName
sparkpost	27	latest/	[].msys.*.type
checkout	22	1.0.25/ (existing)	type (existing, unchanged)
ordinal	0		already upstream (20 files)
wordpress-com	0		no complete doc body exists

Checklist

check	result
yarn compile	passes; providers.json has 146 providers (140 + 6); 0 topic collisions in any provider/version
yarn test	14/14
resolveTopic against every new sample	aftership 1/1, circleci 2/2, grafana 1/1, snipcart 3/3, checkout 22/22: filename == topic == resolved value. docker-hub 0/1 and sparkpost 0/27 don't resolve, which is expected (see below). Nothing mis-resolves.
no doc file at a provider+topic+version that has a capture	holds. The six new providers have nothing upstream. None of the 22 checkout topics is among the 120 checkout files already here, compared by body type.
no hand-written samples for a provider with a scripts/<provider>/ harness	holds. There is no scripts/ directory for any of these seven providers.
header-carried topic_identifier lowercased and equal to the registry's discriminator_path_lookup	circleci circleci-event-type equals the lookup. Every other identifier is a body path and equals its lookup exactly.
regenerate samples-doc/ into a scratch tree and diff	byte-identical for all seven providers (harvest_{aftership,circleci,docker_hub,grafana,snipcart,sparkpost,checkout}.py run against an empty WEBHOOK_SAMPLES_DOC, with WEBHOOK_SAMPLES_DIR set to a clean clone of this repo's main)
registry verify.py	FAIL (0)
existing files changed	0
provenance	docs / 2026-09-28 for each of the six new versions. None for checkout 1.0.25, which is now mixed; it publishes as unknown.

Version directories (rules 2 and 3)

• aftership → 2026-07/. AfterShip versions the webhook payload itself. Each webhook URL picks a YYYY-MM payload version, which arrives as the as-webhook-version header ("included in every webhook request to indicate the payload version", from the Tracking webhook-versioning page). The specifications page the body was read from is served from docs branch production/2026-07, and its header sample shows As-Webhook-Version: 2026-07. The harvester refuses to write if either of those moves. The header isn't synthesized into the file, because a page provides a body, not a delivery.
• circleci, docker-hub, sparkpost → latest/. None of the three documents a payload-version field. circleci's v1= in circleci-signature is the version of the signing scheme, not of the payload. docker-hub's dhi_metadata.*.schema_version versions that one object (the object-version row in rule 3). sparkpost's /api/v1/ is the REST API path of the samples endpoint, not a webhook-contract version.
• snipcart → latest/. The v3 in docs.snipcart.com/v3/ is the platform generation. It isn't a payload version, and the vendor says fields are added "without notice or a new version". The literal v3/ prefix on subscription eventName values is part of the event name, and none of the three exported events carries it. This follows the precedent of nylas, which is under latest/ here although its docs are served under /docs/v3/.
• grafana → latest/. This is a deviation, stated. The default body carries "version": "1", documented as "Version of the payload structure", so rule 2's second source would make the directory 1/. The registry filed it under latest/. That follows the precedent of two providers already merged here with one observed payload version: gemini (version: "v1") and azure-event-grid (metadataVersion: "1"), both under latest/. Grafana hard-codes Version: "1" in webhook.go and has never shipped another value. If maintainers would rather have 1/, the change belongs in the registry harvester (so samples-doc/ and this repo keep agreeing), not here.
• checkout → existing 1.0.25/ (rule 7). The new bodies' version: "1.2.0" is an event-schema version, the checkout row of rule 3's table, not a directory.

topic_identifier choices (rules 4, 6 and 7)

• circleci: circleci-event-type, the header. It's the carrier CircleCI documents as the event type ("The type of event, (workflow-completed, job-completed, etc)"). The same value also appears at body type in all four published samples, but type is missing from the reference's top-level-keys table, so the body field rests on examples alone. Each file carries circleci-event-type equal to its topic, and I checked that it equals body type in both files. This is the only header synthesized beyond content-type. circleci-signature is per-delivery and isn't included.
• docker-hub: none (written as null, which facebook, gocardless, statsig and strava already use). Docker Hub has one trigger, a push. The payload has no event-type key and the page documents no request headers, so there is nothing to resolve. The file's explicit topic: "push" names it. A capture through requestReceiver.ts would be filed as untitled-<md5>, which is correct for a provider with no carrier.
• grafana: status (firing | resolved). Grafana has no event types, and status is the only documented field that tells one notification from another. resolved has no published body, so only firing ships.
• sparkpost: [].msys.*.type, kept as the accurate path. A delivery is a JSON array (a batch) of {"msys": {"<event_class>": {..., "type": "<event>"}}}. The class key varies (message_event, track_event, …), so the path needs a root-array segment and a wildcard. resolveTopic supports neither, so all 27 files resolve to nothing: no mis-resolution, just untitled- on a future capture. Every file carries an explicit topic, and I checked that body[0].msys.<class>.type == topic in all 27. I didn't flatten it to type, which would resolve nowhere and read as a decision (rule 6).
• aftership event, snipcart eventName: top-level body keys that resolve flat.

What's not included, and why

• aftership edd_revise and tracking_pending_time are in the event table but have no body on any Tracking page. The Returns, Warranty and Shipping products are separate surfaces with their own envelopes and aren't pooled in.
• circleci: each event has a second reference sample ("for GitLab and GitHub App"). One file per topic is allowed, so the GitHub OAuth / Bitbucket Cloud variant ships and the source note names the one left out. ping is excluded because its type is undocumented and only a community log shows it.
• docker-hub: the two dhi_metadata examples are excerpts that open with a literal ....
• grafana: resolved (no published body), the Test notification (a firing notification, not a type of its own), and Custom Payload (template output).
• snipcart: 10 of the 13 documented events are left out. The published examples elide structure (... or "...": "..."), lack the documented envelope (order.withdrawal.created has no createdOn), or are content-only fragments. One repair was made: the shippingrates.fetch example as published is invalid JSON with one trailing comma. The comma was deleted, and nothing was added, removed or retyped. The file's source.note records this.
• sparkpost: each body is one element of the samples endpoint's results list wrapped in a one-element array, because deliveries are batches with no results key. The composition is recorded in each source.note. relay_message belongs to Relay Webhooks, a separate product.
• checkout: digital_card_reprovisioned and payouts_disabled have per-event pages whose example body carries a different type, so they're declined rather than filed under a topic their own discriminator contradicts.
• ordinal: all 20 event types are already here. How those files are marked is fixed separately in fix(ordinal): mark the 20 docs-sourced samples as docs-sourced (source block, no invented headers) #59.
• wordpress-com: the support page lists each action's selectable fields but gives no values and no encoding, so any body built from it would be invented.

Headers

Only content-type: application/json is synthesized, plus circleci-event-type for circleci. This is the repo convention for doc samples described in the README. For docker-hub and sparkpost the registry records that the delivery Content-Type value isn't stated on any vendor page, so for those two it's convention, not a vendor claim. No signature headers are included.

These are transcriptions of documentation. As with every doc-sourced entry, a capture would replace them, and provenance: docs keeps all six providers on the capture queue.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
webhook-samples	Ready	Preview	Sep 28, 2026 4:11pm UTC