[yacinekahlerras-turbodocx]

Closes #211

Why

docs/TurboSign/Webhooks.md had a broken verification sample and four statements the API contradicts. Checking every tab against the real SDKs showed it wasn't only the JS one:

Tab	Problem
JavaScript	Passed one object; verifyWebhookSignature takes positional args. A genuine delivery got 401.
Python	from turbodocx import …: ModuleNotFoundError (the package is turbodocx_sdk); wrong keyword names.
Go	Wrong argument order and missing options param: not enough arguments in call to sdk.VerifyWebhookSignature.
.NET	No .NET SDK exists.

What

• SDK Verification Examples:
  • Rewritten against the real SDKs (same code as the SDK webhooks page).
  • Tabs are now JavaScript, Python, PHP, Go, Java and Ruby.
  • Each reads the raw body, verifies it, and points at event, event_id and data.
• Idempotency (header table, best practices, troubleshooting): dedupe on the payload's event_id. X-TurboDocx-Delivery-Id is new on every attempt.
• Retries:
  • "Retried up to 2 more times (3 attempts in total)".
  • The schedule is now concrete: about 1 min, then about 5 min.
• HTTPS: every webhook URL must be HTTPS, even for testing; use an HTTPS tunnel locally.
• URL limit: up to 10 URLs, not 5. The settings screen has no lower limit of its own.

Verified (against a live TurboDocx API)

• Real delivery: a test delivery was sent to the page's JS sample run verbatim behind HTTPS and returned 200.
• Other languages, same delivery:
  • The exact request was replayed to the Go, PHP and Python samples run as servers: 200 each, and 401 for a tampered body.
  • Java and Ruby ran their samples' exact verify calls (their frameworks aren't installed here): true, and false for a tampered body.
• Retries: a test fire at a receiver that always returns 500 produced exactly 3 attempts, about 62s and 313s apart. Each had a new delivery ID and the same event_id.
• URL rules: an http:// URL was rejected ("must be a valid uri with a scheme matching the https pattern"), 11 URLs were rejected ("Maximum 10 webhook URLs allowed"), and 10 were accepted.
• Built site:
  • All six tabs render, and every corrected sentence is shown.
  • No overflow at 390px.
  • docusaurus build passes. Its broken-anchor warnings are all on other pages.

Not changed: the "Try it Now" standalone HMAC samples (including C#/PowerShell). They build the signed string correctly and give no delivery-ID advice.

Review follow-up

• Ruby tab: it now carries the same note the embedded-signing guides use, that the turbodocx-sdk gem isn't on RubyGems yet. The Ruby SDK pages are still hidden drafts, so the tab doesn't link to them.
• Header-name tip: troubleshooting no longer says header names must be lowercase. They are case-insensitive, and the Go and Java samples use canonical case.
• Redirects: Delivery behavior now notes that redirects (3xx) are not followed and count as failures.

Third-pass follow-up

• Go sample: it's now a complete program (func main plus the log import). It used to pass go vet but fail go build when copied verbatim. It now builds as-is, and it accepted a real delivery and rejected a tampered one.
• Delivery Object: it now matches what the API returns: no webhookId, and responseBody, nextRetryAt, errorMessage and status are added, with the status values explained.
• Replays: a manual replay keeps the same event_id, so the dedupe advice now says so.
• Testing: points to the SDK's testWebhook for sending a sample event.
• Small fixes:
  • "Webhooks" is described as a left-menu item in E-Signature Settings, not a tab.
  • regenerateWebhookSecret replaces the nonexistent rotateSecret.
  • Three images have real alt text.
  • The Ruby caveat uses the :::note admonition.

Fourth-pass follow-up

• API Reference objects: the Webhook and Delivery Objects now match what the API returns:
  • UUID ids
  • isActive and isDelivered returned as 1/0, with a note to treat them as truthy
  • metadata, createdBy and deliveryStats added
• Delivery ID header: X-TurboDocx-Delivery-Id is not the delivery id. Replay takes the UUID id.
• testWebhook: payloads are sample data (placeholder ids, evt_test_ event ids, a few differing fields), and the call waits for all retries if the endpoint fails.
• UI wording:
  • "Webhooks" is a left-menu item, now in the heading and alt text too.
  • Delivery History timestamps are per delivery.
  • Any delivery can be replayed.

🤖 Generated with Claude Code

Also in this PR: the Ruby SDK is back (TurboDocx/SDK#45)

The turbodocx-sdk gem is now on RubyGems (0.9.0), so the Ruby SDK docs that were hidden in July come back, in the current SDK docs design (one tabbed page per product plus a setup page per language). Commit 960194c. Part of TurboDocx/SDK#45; close that issue once this merges.

• Product pages (turbosign, deliverable, quote, webhooks): a Ruby tab, after Java, in every language tab group: 36 + 31 + 45 + 28 tabs. Text comes from the old Ruby pages, with text shared by every language kept outside the tabs, as in the original merge. Ruby-only sections (file upload by path or IO, the Rails and Sinatra / Rack examples) get their own Ruby group.
• Brought up to date with what the other languages got while Ruby was hidden: conditional (IF/THEN) field metadata, the error-handling rewrite (the error table lives once on the TurboSign page; product pages point to it), the reminder/expiration and fileName request keys, get_status deadline note, and the wording fixes.
• Checked against the 0.9.0 gem: every TurboSign/Deliverable/TurboQuote/TurboWebhooks/TurboPartner call exists with matching arguments, every public method the gem has is documented where the other languages document it, the error codes and tolerance rules match, and the quote constants exist.
• ruby.md is now a setup page like python.md (Installation, Requirements, Configuration, Product guides, Resources) and is listed under Install & configure. partner-ruby.md is unlisted: true, like its siblings.
• Retired pages: deliverable-ruby, quote-ruby and webhooks-ruby are folded into the tabs; static/_redirects 301s each (plain, /, .html) to ?language=ruby. Old /docs/SDKs/ruby#<section> links hop to the TurboSign page's Ruby tab (src/theme/Root.js).
• Overview and notes: Ruby rows in the four SDK tables and Ruby tabs on the SDKs overview; "the gem is not on RubyGems yet" notes removed (this page's Ruby tab and the embedded-signing overview).

[yacinekahlerras-turbodocx]

Self-review (author): ready to merge. CI green, no conflicts with develop or my other open Docs PRs (#217, #218, #219).

• Wider than the issue. It flagged only the JS tab, but Python, Go and .NET were broken too. Before the fix:

  • JS 401'd a genuine delivery.
  • Go didn't compile.
  • Python failed on import.
  • .NET documented a nonexistent SDK.

  All six tabs now use the real SDK calls, matching docs/SDKs/webhooks.md.

• Each claim was tested live against a real delivery from the API:

  • the samples, run as servers or as exact SDK calls: genuine accepted, tampered rejected
  • 3 attempts at about 1 min and about 5 min, with a new delivery ID each time and a stable event_id
  • HTTPS-only enforcement, and the 10-URL limit

  The settings screen has no URL limit of its own, so "up to 10" is right in the UI walkthrough too.

• Go sample style. It keeps the Docs' 4-space indentation, like the page's other Go blocks and the SDK page, so gofmt -l flags it. go vet and the build are clean.

• Left as is. The "Try it Now" standalone HMAC samples build the signed string correctly and say nothing about delivery IDs.

[yacinekahlerras-turbodocx]

Independent review (second pass): found 3 more things, all fixed in 3502a36.

Found and fixed:

1. Ruby tab. The turbodocx-sdk gem isn't on RubyGems yet, and the Ruby SDK pages are hidden drafts. As written, the tab sent readers to a gem they can't install. It now carries the same note the embedded-signing guides use (install from the SDK repo). It deliberately doesn't link to the hidden Ruby page.
2. Troubleshooting said header names must be lowercase. They are case-insensitive, and the new Go and Java samples read them in canonical case. The tip now says to read the two headers by name and match your framework's lookup.
3. Redirects. Delivery behavior now says redirects (3xx) are not followed and count as a failure, which is what the delivery client does.

Re-confirmed against the SDKs:

• JavaScript: verifyWebhookSignature(rawBody, sig, ts, secret) is exported from @turbodocx/sdk, and the raw Buffer is accepted.
• Python: turbodocx_sdk.verify_webhook_signature is exported.
• PHP: use function TurboDocx\Utils\verifyWebhookSignature matches the namespace, and the function is autoloaded via composer files.
• Go: VerifyWebhookSignature([]byte, …, nil), and every import is used.
• Java: WebhookSignatureVerifier.verify(byte[], …).
• Ruby: keyword args, require "turbodocx_sdk", and the HTTP_X_TURBODOCX_* env keys.

Re-confirmed against the delivery behaviour:

• payload keys and the event_id format
• header names and sha256= format
• 300s tolerance
• 10s timeout
• 3 attempts with 60s/300s backoff
• a new delivery ID per attempt, with a stable event_id
• HTTPS-only, and max 10 URLs
• the seven event names
• the API Reference object fields

Deliberately left as is:

• "Try it Now" C# / PowerShell samples: they hash by hand and need no SDK, so they're valid even though the .NET SDK tab was removed. They build timestamp + "." + body correctly and give no delivery-ID advice.
• Java Spring sample: a missing header yields 400 from @RequestHeader before verification. That matches the SDK page's Spring sample, and it's still a rejection.

Rebuilt: docusaurus build passes (no broken anchors on this page). The page was re-checked in a browser, and all checks passed, including the new note in the Ruby tab. CI green; mergeable.

[yacinekahlerras-turbodocx]

Third review (independent, every sample run): ready to merge. It found more accuracy issues on the page, all fixed in 9e46724. Two of them correct my own earlier comments.

• Go sample (corrects my earlier "build is clean"): it had package main but no main(), so it passed go vet and failed go build when copied verbatim. It's now a complete program. Built as-is, it accepted a real delivery from the API (200) and rejected a tampered copy (401).
• Delivery Object (corrects my earlier "re-confirmed the API Reference fields"): it showed webhookId, which the API doesn't return, and omitted responseBody, nextRetryAt, errorMessage and status. It now matches the response, with the status values (delivered / retrying / failed / pending) explained.
• Replays keep event_id: a manual replay resends the same payload, so it keeps the same event_id. The dedupe advice now says so, so receivers aren't surprised when a replay is skipped.
• Testing: the testing section now points to the SDK's testWebhook for sending a sample event, which is retried and logged like a real one.
• Small fixes:
  • "Webhooks" is a left-menu item in E-Signature Settings, not a tab.
  • regenerateWebhookSecret, not rotateSecret.
  • Three images all had the alt text "Get It Signed button on TurboDocx homepage"; they now describe the image.
  • The Ruby caveat uses the same :::note admonition as the embedded-signing guide.

The reviewer ran every sample:

• JS, Python, PHP and Go as servers, plus the Ruby verify call. Each one: genuine signature 200, tampered 401, stale timestamp 401, missing headers 401.
• Java was checked against the published jar.

Every fact checked against the delivery behaviour and the settings screen:

• events, payload, headers, signature format
• 300s tolerance, 10s timeout
• 3 attempts at 60s/300s
• no redirects, HTTPS-only, max 10 URLs
• UI labels

Rebuilt: docusaurus build passes (no broken anchors on this page), and all browser checks pass, including the 9 new ones.

Out of scope, FYI:

• The issue body cites internal file paths, which this public repo's AGENTS.md asks to avoid.
• Test-fire sample payloads differ slightly from production ones in a few fields.

[yacinekahlerras-turbodocx]

Fourth review (a new developer relying on every sentence, checked against the live API): fixes in 590695d. Ready to merge.

The reviewer test-fired all seven events, replayed a delivery, fetched the webhook and delivery objects, and crawled every link.

Confirmed correct:

• the real payloads' envelope and data fields, for all seven events
• header names and formats
• replay keeps event_id and gets a new delivery
• 3xx is not followed, with 3 attempts at about 1 min and 5 min
• HTTPS enforced on create and update
• the masked-secret format and the delivery status values
• every UI label
• all 52 links and anchors resolve

Found and fixed:

1. "Webhooks tab": the step 3 heading and an alt text still said it, contradicting the corrected bullet. Both now say it's a left-menu item.
2. testWebhook pointer: it now says the payload is sample data. IDs are placeholders, event_id starts with evt_test_, and e.g. voided sends voided_reason instead of void_reason. It also says the call waits for all retries (about 6 min) if the endpoint fails.
3. Delivery ID header: X-TurboDocx-Delivery-Id (del_…) is not the delivery id the API and Delivery History use (a UUID). Replaying with the header value returns 400. The header row now says so.
4. API Reference objects: I said earlier that these matched the API, but they didn't fully.
   • Ids are UUIDs.
   • isActive and isDelivered are returned as 1/0, with a note to treat them as truthy (Go's encoding/json won't decode 1 into a bool).
   • The Webhook Object now includes metadata, createdBy and deliveryStats, and notes availableEvents.
5. Delivery History: timestamps are per delivery, and any delivery can be replayed, not just failed ones. That was confirmed in the settings screen code and the screenshot.

Rebuilt: docusaurus build passes, all 13 earlier browser checks pass, and so do 7 new ones. CI green.

Out of scope, FYI:

• Stale screenshot: signature-webhook-config.png predates the current settings menu (it lacks the Identity Verification and Reminders items and the Configuration / Delivery History tabs). Refreshing it needs a UI capture.
• Test vs real payloads: the test-fire payloads should probably match real ones.
• Delivery service: a failing receiver delays later lifecycle events while retries sleep, and the /test endpoint reports success when all attempts failed.

[yacinekahlerras-turbodocx]

Review summary (4 rounds): found, fixed, false alarms

Found and fixed

Round	Finding	Fix
Issue	The JS verification sample passed one object (rejects every genuine delivery with 401)	Positional args, as the SDK takes
Issue+	The other tabs were broken too: Python ModuleNotFoundError, Go didn't compile, and .NET documented a nonexistent SDK	All six tabs (JS, Python, PHP, Go, Java, Ruby) rewritten against the real SDKs; each accepted a real delivery and rejected a tampered one
Issue	Dedupe on X-TurboDocx-Delivery-Id (new every attempt)	Dedupe on the payload's event_id (stable across retries)
Issue	"Retried up to 3 times"	3 attempts in total, with the real ~1 min / ~5 min backoff (observed live)
Issue	"HTTPS for production environments"	HTTPS required even for testing (http:// rejected live)
Issue	Up to 5 URLs	Up to 10 (11 rejected live; the settings screen has no limit of its own)
2	The Ruby tab pointed at a gem that isn't on RubyGems	:::note caveat, the same one the embedded-signing guide uses
2	The troubleshooting tip said header names must be lowercase	Case-insensitive; read them by name
2	Redirect behaviour wasn't documented	3xx isn't followed and counts as a failure (confirmed live)
3	The Go sample had no main(); go vet passed but go build failed	A complete program; builds verbatim and verified against a real delivery
3	The Delivery Object showed webhookId and omitted fields the API returns	Matches the response; status values explained
3	A manual replay keeps the same event_id	Noted next to the dedupe advice
3	"Webhooks tab" (it's a left-menu item), rotateSecret (it's regenerateWebhookSecret), and three images with "Get It Signed button" alt text	Corrected
4	The step 3 heading and an alt text still said "Webhooks tab"	Corrected
4	testWebhook payloads are sample data, and the call waits for all retries if the endpoint fails	Caveat added
4	The X-TurboDocx-Delivery-Id header (del_…) isn't the delivery id (a UUID) used to replay	Header row says so
4	API objects: ids are UUIDs, isActive / isDelivered come back as 1 / 0, and the Webhook Object lacked metadata, createdBy, deliveryStats	Both objects match the live responses; 1/0 note added
4	Delivery History timestamps are per delivery, and any delivery (not just failed ones) can be replayed	Corrected (confirmed in the settings screen and screenshot)

False alarms / deliberately not changed

• "Remove the 'Try it Now' C# / PowerShell samples, since .NET was dropped." Rejected. They hash by hand and need no SDK. They build timestamp + "." + body correctly and give no delivery-ID advice.
• "Add a link to the Ruby SDK page." Rejected. That page is a hidden draft (the gem isn't published), so the link would 404. The tab gets the install-from-repo note instead.
• "The Java Spring sample returns 400, not 401, when a header is missing." Not changed. It's still a rejection, and it matches the SDK page's Spring sample.
• "The Go sample isn't gofmt-formatted." Intentional. It uses the 4-space style of the Docs' other Go blocks and the SDK page; go vet and go build pass.
• "The settings screen may cap URLs at 5." False. "Add Another URL" has no limit; the API's 10 is the real one.
• Two of my own earlier comments said the Go sample "builds" and the API objects were "re-confirmed". Both were wrong, and both are corrected above (rounds 3 and 4).

Real, but outside #211 (not changed here)

• Stale screenshot: signature-webhook-config.png predates the current settings menu. Refreshing it needs a UI capture.
• Test vs real payloads: test-fire payloads differ from real ones (e.g. voided_reason vs void_reason).
• Delivery service:
  • retries sleep in-process, so a failing receiver delays later lifecycle events by about 6 minutes
  • the test endpoint reports success when all attempts failed

Status: docusaurus build passes (no broken anchors on this page). All browser checks pass, and all 52 links resolve. CI green, mergeable.