Structured responses to webhook events

[bradenkeith]

Description

This PR adds webhook response functionality to handle user registration and authentication actions. The implementation includes:

• Support for both "Allow" and "Deny" verdicts in webhook responses
• Support for "user_registration_action_response" and "authentication_action_response"
• Error message handling for denied verdicts
• JSON serialization support
• Validation for:
  • Response types
  • Verdict values
  • Required error messages for deny verdicts

The changes improve webhook response handling by providing a structured way to respond to webhook events.

Example code in a Laravel app:

Route::post('work-os/user-registration-action', function (Request $request) {
    $webhook = (new Webhook)->constructEvent(
        $request->headers->get('WorkOS-Signature'),
        $request->getContent(),
        config('services.workos.webhook_secret'),
        180
    );
    
    //...

    $response = WebhookResponse::create(
        WebhookResponse::USER_REGISTRATION_ACTION,
        config('services.workos.webhook_secret'),
        WebhookResponse::VERDICT_ALLOW,
    );

    return response()->json($response->toArray(), 200, ['Content-Type' => 'application/json']);
});

This also allows the package to calculate the signature on the user's behalf.

Before this PR, this would have been the user's code for the same thing. 👎

Route::post('work-os/user-registration-action', function (Request $request) {
    $webhook = (new Webhook)->constructEvent(
        $request->headers->get('WorkOS-Signature'),
        $request->getContent(),
        config('services.workos.webhook_secret'),
        180
    );
    
    //...

    // Create response payload
    $responsePayload = [
        'timestamp' => time() * 1000, // Convert to milliseconds to match JS Date.now()
        'verdict' => 'Allow',
    ];
    // Create the signed response
    $timestamp = $responsePayload['timestamp'];
    $payloadString = json_encode($responsePayload);
    $signedPayload = $timestamp.'.'.$payloadString;
    $signature = hash_hmac('sha256', $signedPayload, config('services.workos.webhook_secret'), false);

    $response = [
        'object' => 'user_registration_action_response',
        'payload' => $responsePayload,
        'signature' => $signature,
    ];

    return response()->json($response, 200, ['Content-Type' => 'application/json']);
});

Documentation

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

[] Yes

[nicknisi]

Thanks for the contribution and tests. This provides a simpler DX for working with webhooks!