feat: Add webhook decoder #80

Koosha-Owji · 2026-01-21T03:54:28Z

Explain your changes

Fixes #77 — add PHP equivalent of @kinde/webhooks for webhook JWT validation/decoding, exposing event type constants and a decoder that reuses existing JWKS fetch/cache.

Checklist

I have read the “Pull requests” section in the contributing guidelines.
I agree to the terms within the code of conduct.

🛟 If you need help, consider asking for advice over in the Kinde community.

coderabbitai · 2026-01-21T03:54:47Z

Walkthrough

Adds webhook validation helpers (decoder, event/source enums) and extends JWKS caching/parsing to accept a namespaced JWKS URL for trusted validation and cache isolation.

Changes

Cohort / File(s)	Summary
Webhook utilities `lib/Webhooks/WebhookDecoder.php`, `lib/Webhooks/WebhookEventType.php`, `lib/Webhooks/WebhookSource.php`	New `WebhookDecoder::decodeWebhook(?string $token, ?string $domain): ?array` (normalizes domain, builds JWKS URL, delegates to `Utils::parseJWT`, returns payload or null). New enum-like classes `WebhookEventType` and `WebhookSource` with constants and `all()` helpers.
JWKS cache & lookup (Storage) `lib/Sdk/Storage/Storage.php`	JWKS cache methods now accept optional `?string $jwksUrl` to namespace cache keys: `getCachedJwks(?string $jwksUrl = null)`, `setCachedJwks(array $jwks, int $ttlSeconds = 3600, ?string $jwksUrl = null)`, `clearCachedJwks(?string $jwksUrl = null)`. Added private `getJwksCacheKey(?string $jwksUrl = null): string`.
JWT parsing utility (Utils) `lib/Sdk/Utils/Utils.php`	`parseJWT(string $token, ?string $jwksUrl = null)` now accepts a JWKS URL, validates it via new `validateTrustedJwksUrl(string $jwksUrl): string`, and uses namespaced cache helpers (`getCachedJwks`/`setCachedJwks`/`clearCachedJwks`) when fetching/parsing JWKS.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant Decoder as WebhookDecoder
  participant Utils as Utils::parseJWT
  participant Storage
  participant JWKS as JWKS Endpoint

  Client->>Decoder: decodeWebhook(token, domain)
  Decoder->>Decoder: normalize domain, build jwksUrl
  Decoder->>Utils: parseJWT(token, jwksUrl)
  Utils->>Storage: getCachedJwks(jwksUrl)
  alt cache miss / refresh
    Utils->>JWKS: fetch JWKS from jwksUrl
    JWKS-->>Utils: return keys
    Utils->>Storage: setCachedJwks(keys, ttl, jwksUrl)
  end
  Utils-->>Decoder: return payload or error
  alt payload returned
    Decoder-->>Client: return payload (array)
  else invalid / error
    Decoder-->>Client: return null
  end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: Add webhook decoder' is concise and directly summarizes the main change of adding webhook decoding functionality to the PHP SDK.
Description check	✅ Passed	The PR description is clearly related to the changeset, explaining that it adds a PHP equivalent of `@kinde/webhooks` for JWT validation/decoding and references issue `#77`.
Linked Issues check	✅ Passed	The changeset addresses issue `#77` by providing webhook JWT decoding/validation, WebhookEventType constants, and WebhookSource definitions with domain validation support as discussed in review comments.
Out of Scope Changes check	✅ Passed	All changes are within scope: WebhookDecoder and related classes implement webhook validation per `#77`, while Storage and Utils modifications support the JWKS caching by URL needed for webhook validation.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

Important

Action Needed: IP Allowlist Update

If your organization protects your Git platform with IP whitelisting, please add the new CodeRabbit IP address to your allowlist:

✨ 136.113.208.247/32 (new)
34.170.211.100/32
35.222.179.152/32

Reviews will stop working after February 8, 2026 if the new IP is not added to your allowlist.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@lib/Webhooks/WebhookDecoder.php`:
- Around line 24-33: In decodeWebhook, validate and parse the incoming $domain
before building $jwksUrl: use a URL/host parser (e.g., parse_url or filter_var)
to ensure the scheme is present and equals "https" and that the host is a valid
hostname (reject IPs/private ranges if required), and only then construct
$normalizedDomain and $jwksUrl; if validation fails, return null. Reference:
function decodeWebhook, variables $domain, $normalizedDomain, and $jwksUrl.

lib/Webhooks/WebhookDecoder.php

coderabbitai

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@lib/Webhooks/WebhookDecoder.php`:
- Around line 39-45: The code mutates global JWKS state via
Storage::getInstance()->setJwksUrl($jwksUrl) which causes race conditions;
instead remove that global mutation and pass the JWKS URL directly into the JWT
parsing call (e.g., change Utils::parseJWT($token) to Utils::parseJWT($token,
$jwksUrl) or an equivalent per-call parameter) from WebhookDecoder::...; update
Utils::parseJWT to accept and use the jwksUrl parameter (and preserve existing
exception handling) so each parseJWT call uses the provided jwksUrl and no
shared Storage state is modified.

lib/Webhooks/WebhookDecoder.php

coderabbitai

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

lib/Sdk/Utils/Utils.php (1)

121-137: Fix inconsistent indentation in the error recovery block.

Lines 125 and 130 have excessive leading whitespace that breaks the code's visual consistency.

Proposed fix

         } catch (Exception $e) {
             // If parsing fails with cached JWKS, try to refresh from server
             if ($jwks !== null) {
                 try {
-                        Storage::getInstance()->clearCachedJwks($jwks_url);
+                    Storage::getInstance()->clearCachedJwks($jwks_url);
                     $jwks_json = file_get_contents($jwks_url);
                     $jwks = json_decode($jwks_json, true);
                     
                     if ($jwks && isset($jwks['keys'])) {
-                            Storage::getInstance()->setCachedJwks($jwks, 3600, $jwks_url);
+                        Storage::getInstance()->setCachedJwks($jwks, 3600, $jwks_url);
                         return json_decode(json_encode(JWT::decode($token, JWK::parseKeySet($jwks))), true);
                     }
                 } catch (Exception $refreshException) {

KeeganBeuthin · 2026-01-21T10:05:57Z

will look through this today

KeeganBeuthin · 2026-01-21T15:21:26Z

Hey @Koosha-Owji, just finished running through this. Overall quality looks good and I’m happy with the approach.

Just wanted to check a couple things with you as well. Would you be open to adding a lightweight domain guard to prevent untrusted domains being used to fetch JWKS?

Also, can you confirm the customer requirement is strictly signature validation + decode, or do they expect additional claim checks, iss/aud/typ?

Koosha-Owji · 2026-01-23T05:08:32Z

Hello @KeeganBeuthin Yes my understanding it they are looking for the same functionality as the https://github.com/kinde-oss/webhook

lib/Sdk/Utils/Utils.php

lib/Webhooks/WebhookDecoder.php

Koosha-Owji · 2026-02-05T04:26:02Z

@KeeganBeuthin I have addressed your comments.

feat: Add webhook decoder

fff16c2

Koosha-Owji requested a review from a team as a code owner January 21, 2026 03:54

coderabbitai bot requested changes Jan 21, 2026

View reviewed changes

lib/Webhooks/WebhookDecoder.php Show resolved Hide resolved

chore: fix coderabbit comment

8e0c472

coderabbitai bot requested changes Jan 21, 2026

View reviewed changes

lib/Webhooks/WebhookDecoder.php Show resolved Hide resolved

chore: Namespace JWKS cache per JWKS URL

a23182d

coderabbitai bot reviewed Jan 21, 2026

View reviewed changes

coderabbitai bot approved these changes Jan 21, 2026

View reviewed changes

chore: delete extra space

3bd281a

Koosha-Owji requested a review from KeeganBeuthin January 21, 2026 04:23

chore: Guard JWKS fetches against untrusted domains

e494111

KeeganBeuthin requested changes Jan 29, 2026

View reviewed changes

lib/Sdk/Utils/Utils.php Show resolved Hide resolved

lib/Webhooks/WebhookDecoder.php Show resolved Hide resolved

chore: fail-close JWKS domain validation and seed webhook JWKS host

dfb5356

Koosha-Owji requested a review from KeeganBeuthin February 9, 2026 03:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add webhook decoder #80

feat: Add webhook decoder #80

Koosha-Owji commented Jan 21, 2026

Uh oh!

coderabbitai bot commented Jan 21, 2026 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

coderabbitai bot left a comment

Uh oh!

KeeganBeuthin commented Jan 21, 2026

Uh oh!

KeeganBeuthin commented Jan 21, 2026

Uh oh!

Koosha-Owji commented Jan 23, 2026

Uh oh!

Uh oh!

Uh oh!

Koosha-Owji commented Feb 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: Add webhook decoder #80

Are you sure you want to change the base?

feat: Add webhook decoder #80

Conversation

Koosha-Owji commented Jan 21, 2026

Explain your changes

Checklist

Uh oh!

coderabbitai bot commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

KeeganBeuthin commented Jan 21, 2026

Uh oh!

KeeganBeuthin commented Jan 21, 2026

Uh oh!

Koosha-Owji commented Jan 23, 2026

Uh oh!

Uh oh!

Uh oh!

Koosha-Owji commented Feb 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coderabbitai bot commented Jan 21, 2026 •

edited

Loading