feat(webhooks): verifyAndParse* API for compressed payloads (CHA-3071)#169
Open
nijeesh-stream wants to merge 5 commits intomainfrom
Open
feat(webhooks): verifyAndParse* API for compressed payloads (CHA-3071)#169nijeesh-stream wants to merge 5 commits intomainfrom
nijeesh-stream wants to merge 5 commits intomainfrom
Conversation
Adds Client::decompressWebhookBody and Client::verifyAndDecodeWebhook so handlers can accept the new outbound webhook compression (GetStream/chat#13222) without changing how X-Signature is verified. decompressWebhookBody runs gzdecode when the Content-Encoding header is gzip, returns the body unchanged when the header is null or empty, and throws StreamException for any other value with a message that points the operator at the app's webhook_compression_algorithm setting. verifyAndDecodeWebhook chains decompression with the existing HMAC check and returns the raw JSON when the signature matches. The signature is always computed over the uncompressed bytes, matching the server. verifyWebhook switches to hash_equals so the comparison is constant-time. Tests cover gzip round-trip, null/empty/whitespace passthrough, case- insensitive Content-Encoding, invalid gzip bytes, every non-gzip encoding being rejected with a clear message, signature mismatch, and the regression case where the signature was computed over the compressed bytes. Co-authored-by: Cursor <cursoragent@cursor.com>
Extends `decompressWebhookBody` and `verifyAndDecodeWebhook` with an optional `$payloadEncoding` argument. When set to "base64" (the wrapper Stream applies for SQS / SNS firehose so the message stays valid UTF-8 over the queue), the body is base64-decoded before gzip decompression. The HMAC signature continues to be computed over the innermost (uncompressed, base64-decoded) JSON, so the verification rule is invariant across HTTP webhooks and SQS / SNS. `null` / `""` for payloadEncoding is a no-op, so the HTTP webhook path is byte-identical to before this change. Default value of `null` preserves backward compatibility with the previous 3-argument call. Co-authored-by: Cursor <cursoragent@cursor.com>
Replaces verifyAndDecodeWebhook / decompressWebhookBody with the cross-SDK contract documented at https://getstream.io/chat/docs/node/webhooks_overview/. Helpers on Client: Static primitives: Client::ungzipPayload - gzip magic-byte detection + inflate Client::decodeSqsPayload - base64 then ungzip-if-magic Client::decodeSnsPayload - alias for decodeSqsPayload Client::verifySignature - constant-time HMAC-SHA256 comparison (parameter order matches the cross-SDK spec: body, signature, secret) Client::parseEvent - JSON -> array (typed event lands later) Instance composite (return parsed event array): \$client->verifyAndParseWebhook(\$body, \$signature) \$client->verifyAndParseSqs(\$messageBody, \$signature) \$client->verifyAndParseSns(\$message, \$signature) The composite functions auto-detect compression from body bytes, so the same handler stays correct whether or not Stream is currently compressing payloads, and behind middleware that auto-decompresses. The legacy \$client->verifyWebhook(\$body, \$signature) bool helper is kept for backward compatibility (now delegates to verifySignature). Co-authored-by: Cursor <cursoragent@cursor.com>
nijeesh-stream
changed the title
RFC 1952 defines the gzip magic number as the two-byte sequence 1F 8B; the third byte (CM) is informational and not part of the identifier. Trim the magic check from three bytes to two to match the spec and stay consistent with the reference implementations in the public docs. Co-authored-by: Cursor <cursoragent@cursor.com>
Mirrors the Ruby StreamChat::Webhook module / Java App.* / .NET WebhookHelpers shape: `Webhook::verifyAndParseWebhook($body, $signature, $secret)` (and the SQS / SNS variants) are now available as static methods with an explicit `secret` argument, alongside the primitives ungzipPayload, decodeSqsPayload, decodeSnsPayload, verifySignature, parseEvent. `Client::verifyAndParseWebhook` (and the SQS / SNS variants) still work as 2-arg instance methods that pull the secret from the configured client; they now delegate to the new static helpers so the two surfaces stay in lockstep. Tests cover the new static class, the parity between the two surfaces, and the existing regression cases. Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds first-class support for gzip-compressed webhook payloads (HTTP webhooks, SQS, SNS) and exposes a stable
verifyAndParse*API that mirrors the cross-SDK contract published in Webhooks Overview.New public API (
GetStream\\StreamChat\\Client)Static primitives:
ungzipPayload(string): string— gzip-magic-byte detection, no-op when not compresseddecodeSqsPayload(string): string/decodeSnsPayload(string): string— base64 decode then ungzip-if-magicverifySignature(string, string, string): bool— constant-time HMAC-SHA256 over the uncompressed bodyparseEvent(string): array— JSON → associative arrayInstance composites (return
array):verifyAndParseWebhook(string \$body, string \$signature): arrayverifyAndParseSqs(string \$body, string \$signature): arrayverifyAndParseSns(string \$body, string \$signature): arrayBackwards compatibility
\$client->verifyWebhook(\$body, \$signature)is preserved and now delegates toClient::verifySignature. The experimentaldecompressWebhookBodyandverifyAndDecodeWebhooksurfaces are removed (they were never released).Tests
tests/unit/WebhookCompressionTest.phpcovers plain / gzip / base64 / base64+gzip payloads, signature mismatches, malformed bytes, and JSON parsing into an associative array. Linked Linear ticket: CHA-3071.Test plan
php-cs-fixer fix— clean