Feat: Add Webhook Signature Verification

[Radiergummi]

What:

• Bug Fix
• New Feature

Description:

This PR adds

1. a new enum for all webhook events as listed in the OpenAI docs, and
2. a signature verifier to validate webhook signature headers OpenAI sends with webhook requests as described in their documentation and the Standard Webhooks Spec.

This provides some primitives required to add webhook support to their app, which allows for asynchronous LLM workflows where you don't want to (or can't) wait for several minutes until the model provides the response, and instead get notified when the results are available.
While HTTP request handling and result processing is firmly out of scope for this library itself, the verification mechanism is security sensitive and interested users will definitely benefit from not having to implement it themselves.
Additionally, it will allow for adding more integrated webhook handling to the framework-specific packages later on.

Related:

This will solve #721 and provide the requirements for openai-php/laravel#186.

fixes: #721

[iBotPeaches]

thanks! Looks nice on first peek. Let me setup my side to actually run this through with ngrok and test it out.

[iBotPeaches]

All my tests worked and I have no comments. Great PR!

[2025-12-10 19:59:21] local.INFO: Webhook signature verified successfully. {"headers":{"host":["xxx.com"],"user-agent":["OpenAI/1.0 (+https://platform.openai.com/docs/webhooks)"],"content-length":["147"],"accept":["*/*"],"accept-encoding":["gzip, deflate, br"],"content-type":["application/json"],"webhook-id":["wh_6939d11908d4819089e0518971a412c2"],"webhook-signature":["v1,TP6fT1r0nBGn4K9P3wcHr0Um/clOCjCWtRhnc7VY29A="],"webhook-timestamp":["1765396761"],"x-forwarded-for":["13.65.138.121"],"x-forwarded-proto":["https"]},"body":"{\"id\": \"evt_6939d11908d48190af662c3ec54c7c51\", \"object\": \"event\", \"created_at\": 1765396761, \"type\": \"batch.failed\", \"data\": {\"id\": \"batch_abc123\"}}"}