Add Actions helper class for WorkOS Actions support

[blobaugh]

Description

Add Actions helper class for WorkOS Actions support

• Add Actions.php service class with convenient wrapper methods for WebhookResponse and Webhook functionality
• Add test suite
• Include detailed docblocks with usage examples for all methods

New Methods:

• allowUserRegistration() / denyUserRegistration() - User registration responses
• allowAuthentication() / denyAuthentication() - Authentication responses
• verifyWebhook() / parseWebhook() - Webhook handling
• isUserRegistrationWebhook() / isAuthenticationWebhook() - Type checking
• extractEmail() / extractUserId() / extractOrganizationId() - Data extraction

This makes WorkOS Actions support highly discoverable while maintaining consistency with existing SDK patterns. All methods delegate to existing WebhookResponse and Webhook classes without duplication.

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[ ] Yes

If yes, link a related docs PR and add a docs maintainer as a reviewer. Their approval is required.

[greptile-apps]

Greptile Overview

Summary

Adds a new Actions helper class that provides convenient wrapper methods for WorkOS Actions support, enabling user registration and authentication flow controls.

Key Changes:

• New Actions.php class with methods for allowing/denying user registration and authentication
• Webhook verification and parsing helpers (verifyWebhook, parseWebhook)
• Type-checking utilities (isUserRegistrationWebhook, isAuthenticationWebhook)
• Data extraction methods (extractEmail, extractUserId, extractOrganizationId)
• Comprehensive test suite with edge case coverage
• Documentation link added to README

The implementation follows existing SDK patterns by delegating to WebhookResponse and Webhook classes without duplicating logic. All methods include detailed docblocks with usage examples for discoverability.

Confidence Score: 5/5

• This PR is safe to merge with no issues found
• The implementation is clean, well-documented, and thoroughly tested. It follows existing SDK patterns by wrapping existing functionality without duplicating logic. Input validation is handled by the underlying WebhookResponse class. No security concerns, no breaking changes, and comprehensive test coverage including edge cases.
• No files require special attention

Important Files Changed

File Analysis

Filename	Score	Overview
lib/Actions.php	5/5	New helper class for WorkOS Actions - clean wrapper around existing WebhookResponse and Webhook functionality with comprehensive docblocks
tests/WorkOS/ActionsTest.php	5/5	Comprehensive test coverage for Actions class with all major use cases covered
README.md	5/5	Documentation link added for Actions Guide

Sequence Diagram

sequenceDiagram
    participant App as Application
    participant Actions as Actions Class
    participant WH as Webhook Class
    participant WHR as WebhookResponse

    Note over App,WHR: User Registration Flow
    App->>Actions: Receive webhook (POST)
    Actions->>WH: verifyWebhook(signature, payload, secret)
    WH->>WH: verifyHeader()
    WH-->>Actions: true/false
    
    alt Valid Signature
        Actions->>Actions: parseWebhook(payload)
        Actions->>Actions: isUserRegistrationWebhook()
        Actions->>Actions: extractEmail(webhook)
        
        alt Allow Registration
            App->>Actions: allowUserRegistration(secret, reason)
            Actions->>WHR: create(USER_REGISTRATION_ACTION, secret, ALLOW)
            WHR->>WH: computeSignature()
            WHR-->>Actions: WebhookResponse
            Actions-->>App: Response with signature
        else Deny Registration
            App->>Actions: denyUserRegistration(secret, reason)
            Actions->>WHR: create(USER_REGISTRATION_ACTION, secret, DENY, reason)
            WHR->>WH: computeSignature()
            WHR-->>Actions: WebhookResponse
            Actions-->>App: Response with signature
        end
    else Invalid Signature
        App->>App: Return 401 Unauthorized
    end

    Note over App,WHR: Authentication Flow
    App->>Actions: Receive webhook (POST)
    Actions->>WH: verifyWebhook(signature, payload, secret)
    WH-->>Actions: true/false
    
    alt Valid Signature
        Actions->>Actions: parseWebhook(payload)
        Actions->>Actions: isAuthenticationWebhook()
        Actions->>Actions: extractUserId(webhook)
        
        alt Allow Authentication
            App->>Actions: allowAuthentication(secret, reason)
            Actions->>WHR: create(AUTHENTICATION_ACTION, secret, ALLOW)
            WHR-->>Actions: WebhookResponse
            Actions-->>App: Response with signature
        else Deny Authentication
            App->>Actions: denyAuthentication(secret, reason)
            Actions->>WHR: create(AUTHENTICATION_ACTION, secret, DENY, reason)
            WHR-->>Actions: WebhookResponse
            Actions-->>App: Response with signature
        end
    end

Loading

_{3 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[nicknisi]

Looks good, overall! Just a few minor comments. I'll also look into that webhook bug. Thanks!

[nicknisi]

suggestion: Should this namespace just be WorkOS for consistency with other tests?

Suggested change

	namespace WorkOS\Tests;
	namespace WorkOS;

[nicknisi]

Ooh, I'll look into this.

[nicknisi]

suggestion: Consider adding a combined verifyAndParseWebhook($signatureHeader, $payload, $secret) method that does both steps. This would prevent developers from accidentally parsing untrusted payloads.

Alternatively, update the parseWebhook docblock example to show the full secure flow:

// Verify first!
if (!$actions->verifyWebhook($signatureHeader, $payload, $secret)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Then parse
$webhook = $actions->parseWebhook($payload);

Either approach works! Just want to make the secure path obvious.