fix: Separate an unreadable webhook payload from a forged one

[razor-x]

Fixes finding M5 from the cross-SDK audit.

Renamed to InvalidWebhookPayloadError per review, and rebased onto beta at 4ee0b79 (4.0.0-beta.16).

The problem

SeamWebhook::verify raised Svix's WebhookVerificationException for a payload whose signature had already matched:

$this->webhook->verify($payload, $normalized_headers);   // signature is good

$event = Event::from_json(json_decode($payload));

if ($event === null) {
    throw new WebhookVerificationException(
        "The verified webhook payload did not contain an event",
    );
}

The message admits verification succeeded, but the exception type says otherwise, and the README maps that type to HTTP 400. So an unreadable delivery was answered with an error and Svix redelivered it across its full backoff schedule — a payload that will never parse, retried for hours — while whoever read the logs saw a verification failure and went looking for a forgery.

A correctly signed payload that parsed but wasn't an event was worse: Event::from_json returned an all-null Event and verify handed it back with no signal at all.

Neither path had any test coverage.

The fix

A new Seam\InvalidWebhookPayloadError implements SeamException for "verified, but the body is not a readable event". Signature failures keep raising WebhookVerificationException.

The two cases now warrant different responses, and the README shows both:

} catch (Svix\Exception\WebhookVerificationException $error) {
    http_response_code(401);
} catch (Seam\InvalidWebhookPayloadError $error) {
    http_response_code(204);
}

Also in this PR:

• Catch the JSON parse failure explicitly via json_last_error() rather than inferring it from a null event, so malformed JSON is distinguishable from a well-formed non-event.
• Treat a signed payload with no event_id as unreadable instead of returning an all-null Event.
• Cast header names before lowercasing: an all-digit header name arrives as an int key and would TypeError in strtolower.

This also closes a hole in SeamException's stated promise that one catch block covers everything the SDK raises — until now the webhook path could only throw an external Svix type.

Tests

The suite had 4 tests covering the happy path and forgery. Now 13. Every new unreadable-payload case fails against beta in one of the two ways the audit described — three raise WebhookVerificationException (parse failure read as forgery), two return an all-null Event with no exception:

{not json, null, `` (empty), [1, 2], `{"hello":"world"}`

Plus the expired-timestamp and missing-header cases the suite never had.

Full suite: 237 tests green, psalm clean, npm run lint clean.

Not in this PR

The audit also flags the svix constraint (^1.40, locked at v1.99.1) as wide for a security-critical dependency, and the hard-coded 5-minute tolerance as unconfigurable. Both are dependency-policy calls rather than defects, so I left them alone — happy to tighten the constraint if you want it.

---

Generated by Claude Code