fix: correct verification facts in 7 skills

[garethx]

Fixes verification facts in seven provider skills that disagreed with the vendor's own docs or official SDK source. Each fix also updates that provider's notes in providers.yaml, so regenerating the skill won't bring the error back. Example code changed only for GitLab and Adyen. The other five fixes are prose only.

Twilio was also on the list, but the skill and its brief already say HMAC-SHA1 with X-Twilio-Signature, so nothing changed there. The Twilio error (HMAC-SHA256 listed as an algorithm, and I-Twilio-Idempotency-Token listed as a secret header) is in the webhook-registry row, which is a different repo.

GitLab (gitlab-webhooks)

Was wrong: "GitLab uses simple token comparison (not HMAC)". The skill covered only X-Gitlab-Token.

Now: Since GitLab 19.0 (GA in 19.1) a webhook can have a signing token, and GitLab recommends it. Delivery follows the Standard Webhooks spec:

• signed content: {webhook-id}.{webhook-timestamp}.{raw body}
• key: the signing token with whsec_ stripped, then base64-decoded
• webhook-signature holds space-separated v1,<base64> HMAC-SHA256 values
• compare in constant time

X-Gitlab-Token is kept as the legacy option. All three examples verify the signature over the raw body when webhook-signature is present, and fall back to X-Gitlab-Token otherwise, which is GitLab's migration advice. A request that carries a signature never falls back to the token.

GitLab says to check that webhook-timestamp is "recent" but gives no number, and the spec only asks for "some allowable tolerance". The examples use 5 minutes, which is the default in the Standard Webhooks reference libraries. The SKILL.md, references, example READMEs, .env.example files, root README row and marketplace description are updated to match.

Sources:

• https://docs.gitlab.com/user/project/integrations/webhooks/#signing-tokens: "The signature is computed over the string {message_id}.{timestamp}.{body}" and "The secret token is not recommended for new webhooks."
• https://docs.gitlab.com/api/project_webhooks/: signing_token "Must be in whsec_<base64> format encoding a 32-byte key."
• https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md: "within some allowable tolerance". The reference libraries use WEBHOOK_TOLERANCE_IN_SECONDS = 5 * 60.

Tests: 8 new tests per suite. They include the published Standard Webhooks test vector (msg_p5jXN8AQM9LWM0D4loKWxJek, 1614265330, v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=), a match on one of several signatures, a tampered body, the wrong key, a stale timestamp, no fallback on a bad signature, and a missing webhook-id.

• express: 26 passed (was 18)
• nextjs: 26 passed (was 18), run on Node 24.11.1 / npm 11.6.2
• fastapi: 27 passed (was 19), in a fresh venv from requirements.txt
• validate-provider.sh gitlab-webhooks: PASSED

Adyen (adyen-webhooks)

Was wrong: "Each field value is escaped (\ → \\, : → \:)". The Python snippets and examples/fastapi escaped each value before joining.

Now: The eight values are joined with : exactly as they are, with no escaping. The escaping is removed from SKILL.md, references/verification.md and examples/fastapi/main.py. The difference only shows when a signed field such as merchantReference contains : or \. In that case the old FastAPI code would reject a genuine delivery. The Express and Next.js examples use the SDK, which already did this correctly.

Sources:

• https://docs.adyen.com/development-resources/webhooks/secure-webhooks/verify-hmac-signatures/: "use a colon (":") to delimit the values". Escaping is not mentioned.
• @adyen/api-library 32.2.0, hmacValidator.getDataToSign: for a NotificationRequestItem it runs signedDataList.join(HmacValidator.DATA_SEPARATOR). The escaping branch only runs for objects whose values are all strings. The Java, Python, PHP and Ruby libraries also join without escaping.

Tests: Added a regression test to each suite: a merchantReference of Order:42\A must be signed verbatim.

• express: 12 passed
• nextjs: 10 passed (Node 24)
• fastapi: 14 passed, including Adyen's documented reference signature
• validate-provider.sh adyen-webhooks: PASSED

Square (square-webhooks)

Was wrong: "Square also still sends a deprecated x-square-signature (HMAC-SHA1) header". The overview table said "Legacy ... still sent, deprecated".

Now: Square's docs document only x-square-hmacsha256-signature. x-square-signature is described as undocumented and seen on a live sandbox delivery (2026-08, square-version: 2026-07-15). The skill no longer calls it deprecated or legacy on Square's authority. It also doesn't claim Square has stopped sending it, because that can't be verified.

Source: https://developer.squareup.com/docs/webhooks/step3validate: "All webhook notifications from Square include an x-square-hmacsha256-signature header." None of the webhook pages in Square's llms.txt mention x-square-signature.

Tests: prose only. validate-provider.sh square-webhooks: PASSED

Intercom (intercom-webhooks)

Was wrong: "X-Body-Signature | (Some accounts) alternate name for the same value"

Now: X-Hub-Signature (sha1=<hex HMAC-SHA1>) is the only webhook signature header. A note explains that X-Body-Signature signs Canvas Kit requests with HMAC-SHA256, which is a different product.

Sources:

• https://developers.intercom.com/docs/references/webhooks/webhook-models: "Intercom signs webhook notifications via an X-Hub-Signature header."
• https://developers.intercom.com/docs/canvas-kit: "Each Canvas Kit request is signed by Intercom via an X-Body-Signature header."

Tests: prose only. validate-provider.sh intercom-webhooks: PASSED

Linear (linear-webhooks)

Was wrong: "Linear has no first-party Node SDK helper for verifying webhooks" and "@linear/sdk ... does not ship a webhook verification helper"

Now: Documents LinearWebhookClient from @linear/sdk/webhooks (v97.0.0). Its verify(rawBody, signature) checks the hex HMAC-SHA256 against Linear-Signature, enforces ±60 s on the signed webhookTimestamp, and throws on failure. The manual examples are kept because they do the same checks.

Source: https://github.com/linear/linear/blob/master/packages/sdk/src/webhooks/client.ts: public verify(rawBody: Buffer, signature: string, timestamp?: number | string): boolean. I confirmed this in the published 97.0.0 tarball, whose exports include ./webhooks.

Tests: prose only. validate-provider.sh linear-webhooks: PASSED

HubSpot (hubspot-webhooks)

Was wrong: "HubSpot does not provide an SDK helper for webhook signature verification"

Now: Documents the helper in each official SDK:

• Node @hubspot/api-client 14.0.1: Signature.isValid
• PHP 14.1.0: \HubSpot\Utils\Signature::isValid
• Python 12.0.0: Signature.is_valid
• Ruby 20.0.0: Hubspot::Helpers::Signature#is_valid

All four support v1, v2 and v3, and raise on a v3 timestamp older than 5 minutes. Two caveats are noted: the helpers take the URL as given, and the Node helper compares with ===. The manual examples are kept.

Sources:

• https://github.com/HubSpot/hubspot-api-nodejs/blob/14.0.1/src/utils/signature.ts: public static isValid(...), MAX_ALLOWED_TIMESTAMP = 300000
• https://github.com/HubSpot/hubspot-api-python/blob/v12.0.0/hubspot/utils/signature.py: def is_valid(

Tests: prose only. validate-provider.sh hubspot-webhooks: PASSED

Stripe (stripe-webhooks)

Was wrong: "The v1 signature is the current version. Ignore v0 (legacy)."

Now: v1 is the only valid live scheme. v0 is a fake signature that Stripe adds to test events to aid testing. Ignore it, but it is not a legacy scheme.

Source: https://docs.stripe.com/webhooks: "To aid with testing, Stripe sends an additional signature with a fake v0 scheme, for test events."

Tests: prose only. validate-provider.sh stripe-webhooks: PASSED

🤖 Generated with Claude Code