[cadesark]

Description

Linear ticket: Refs FSDK-2380

Twilio's real SharedKey header is a named key/value list, not <keyId><delimiter><algorithm>:

X-Twilio-Webhooks-Signature-Settings: key=webhooks_sharedkey_<id>,algorithm=HMAC_SHA256

With the current algorithm-header (header + key-id-delimiter + algorithms) the generated verifyRequest splits at the last , and hands the resolver key=webhooks_sharedkey_<id> and looks up algorithm=HMAC_SHA256. This PR adds two optional fields so the CLI can express the named-parameter format; generators parse it in a follow-up PR against IR 67.33.0.

Changes Made

• WebhookAlgorithmHeaderSchema (fern-definition, shared with api.settings.webhook-signature): optional key-id-parameter / algorithm-parameter.

  algorithm-header:
    header: X-Twilio-Webhooks-Signature-Settings
    key-id-delimiter: ","
    key-id-parameter: key
    algorithm-parameter: algorithm
    algorithms: { HMAC_SHA1: sha1, HMAC_SHA256: sha256 }

• IR 67.33.0: WebhookAlgorithmHeader.keyIdParameter / algorithmParameter (optional, additive); converter passes them through.
• Regenerated fern-definition schema, ir-sdk, JSON schemas; CLI fix changelog entry.
• ETE fixture api-webhook-signature switched to Twilio's real header/format.
• Updated README.md generator (not applicable)

Testing

• Unit tests added/updated — ir-generator tests (34/34), ETE ir test for api-webhook-signature re-snapshotted with the new fields.
• Manual testing completed — dev CLI fern ir on the fixture emits keyIdParameter: "key", algorithmParameter: "algorithm".

Link to Devin session: https://app.devin.ai/sessions/019eb509a709495aad58cca9c4d15756
Open in Devin Desktop: https://app.devin.ai/desktop/session/019eb509a709495aad58cca9c4d15756?variant=devin
Requested by: @cadesark

---

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[nitpickybot]

AI Review Summary

This PR adds optional key-id-parameter / algorithm-parameter fields to the webhook algorithm-header schema (fern-definition + IR 67.33.0) so named key/value settings headers like Twilio's can be expressed, with pass-through in the IR converter and regenerated schemas/snapshots. The core change is small and additive and looks correct. The main concern is that fern-yml.schema.json appears to have been regenerated against a stale source, dropping unrelated existing properties and enum values.

• 🔴 1 critical issue(s)
• 🔵 1 suggestion(s)

---

AI Review

🔴 critical — fern-yml.schema.json (line 1043)

This regeneration looks like it was run against a stale branch: it removes existing enum values (alpha, preview, legacy) from availability across many sites, and deletes unrelated properties (robots-txt-on-instance-url, hide-webhook-method-badges, sort-by-availability, the cli generator entry) elsewhere in this file. Since these schemas drive editor validation, users with valid configs would start seeing bogus "not allowed" errors. None of this is related to the webhook algorithm-header change — please rebase onto latest main and regenerate so fern-yml.schema.json only gains the new key-id-parameter / algorithm-parameter fields (which, notably, are missing from this file entirely while present in the other three schema files).

Review Scope

• Mode: Full pull request
• Range: Full pull request through d5df56387458a5cdb42849ff5e47131a3bd6fe6c
• Current range coverage: Complete
• Cumulative pull request coverage: Complete

---

This review is complete for the current scope. Addressing all critical and warning findings above satisfies the review; suggestions are optional. Request another review only if subsequent changes introduce new behavior or materially expand the pull request's scope.

[devin-ai-integration]

✅ Devin resolved the finding on d5df563

Fixed by Devin (1)

• Valid docs settings fail schema validation

View all findings in Devin Review

[github-actions]

Docs Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-10-16T04:05:51Z).

Fixture	main	PR	Delta
docs	139.5s (n=5)	152.5s (35 versions)	+13.0s (+9.3%)

Docs generation runs fern generate --docs --preview end-to-end against the benchmark fixture with 35 API versions (each version: markdown processing + OpenAPI-to-IR + FDR upload).
Delta is computed against the nightly baseline on main.
Baseline from nightly run(s) on main (latest: 2026-10-16T04:05:51Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-10-16 15:50 UTC

[github-actions]

SDK Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-10-16T04:05:51Z).

Full benchmark table (click to expand)

Generator	Spec	main (generator)	main (E2E)	PR (generator)	Delta
csharp-sdk	square	71s (n=5)	109s (n=5)	72s	+1s (+1.4%)
go-sdk	square	106s (n=5)	227s (n=5)	133s	+27s (+25.5%)
java-sdk	square	175s (n=5)	207s (n=5)	144s	-31s (-17.7%)
php-sdk	square	58s (n=5)	N/A	60s	+2s (+3.4%)
python-sdk	square	123s (n=5)	182s (n=5)	151s	+28s (+22.8%)
ruby-sdk-v2	square	77s (n=5)	111s (n=5)	95s	+18s (+23.4%)
rust-sdk	square	202s (n=5)	171s (n=5)	223s	+21s (+10.4%)
swift-sdk	square	58s (n=5)	304s (n=5)	60s	+2s (+3.4%)
ts-sdk	square	136s (n=5)	141s (n=5)	130s	-6s (-4.4%)

main (generator): generator-only time via --skip-scripts (includes Docker image build, container startup, IR parsing, and code generation — this is the same Docker-based flow customers use via fern generate). main (E2E): full customer-observable time including build/test scripts (nightly baseline, informational). Delta is computed against generator-only baseline.
⚠️ = generation exited with a non-zero exit code (timing may not reflect a successful run).
Baseline from nightly runs on main (latest: 2026-10-16T04:05:51Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-10-16 15:53 UTC