feat: webhooks (64bit#462)

* types for webhook; traits for events

* checkpoint: working webhooks

* updates

* return string which failed deserialiaztion

* update

* webhook feature flag

* update example

* update readme

* cleanup

(cherry picked from commit 890bb6a)

Author: 64bit

async-openai/Cargo.toml

@@ -27,6 +27,7 @@ native-tls = ["reqwest/native-tls"]
 native-tls-vendored = ["reqwest/native-tls-vendored"]
 realtime = []
 byot = []
+webhook = ["dep:hmac", "dep:sha2", "dep:hex"]
 
 [dependencies]
 async-openai-macros = { path = "../async-openai-macros", version = "0.1.0" }
@@ -43,6 +44,10 @@ secrecy = { version = "0.10", features = ["serde"] }
 pin-project = "1.1"
 bytes = "1.9"
 eventsource-stream = "0.2"
+hmac = { version = "0.12", optional = true, default-features = false}
+sha2 = { version = "0.10", optional = true, default-features = false }
+hex = { version = "0.4", optional = true, default-features = false }
+
 
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 rand = "0.9"

async-openai/README.md

@@ -89,6 +89,10 @@ Only types for Realtime API are implemented, and can be enabled with feature fla
 
 Again, the types do not bundle with a specific WS implementation. Need to convert a client event into a WS message by yourself, which is just simple `your_ws_impl::Message::Text(some_client_event.into_text())`.
 
+## Webhooks
+
+Support for webhook event types, signature verification, and building webhook events from payloads can be enabled by using the `webhook` feature flag.
+
 ## Image Generation Example
 
 ```rust

async-openai/src/embedding.rs

@@ -64,6 +64,7 @@ impl<'c, C: Config> Embeddings<'c, C> {
 
 #[cfg(test)]
 mod tests {
+    use crate::error::OpenAIError;
     use crate::types::{CreateEmbeddingResponse, Embedding, EncodingFormat};
     use crate::{Client, types::CreateEmbeddingRequestArgs};
 

async-openai/src/lib.rs

@@ -179,6 +179,8 @@ mod vector_store_file_batches;
 mod vector_store_files;
 mod vector_stores;
 mod video;
+#[cfg(feature = "webhook")]
+pub mod webhooks;
 
 pub use assistants::Assistants;
 pub use audio::Audio;

async-openai/src/traits.rs

@@ -5,3 +5,15 @@ pub trait AsyncTryFrom<T>: Sized {
     /// Performs the conversion.
     fn try_from(value: T) -> impl std::future::Future<Output = Result<Self, Self::Error>> + Send;
 }
+
+/// Trait for events to get their event type string.
+pub trait EventType {
+    /// Returns the event type string (e.g., "batch.cancelled")
+    fn event_type(&self) -> &'static str;
+}
+
+/// Trait for events to get their event ID.
+pub trait EventId {
+    /// Returns the event ID
+    fn event_id(&self) -> &str;
+}

async-openai/src/types/mod.rs

@@ -34,6 +34,9 @@ mod upload;
 mod users;
 mod vector_store;
 mod video;
+#[cfg_attr(docsrs, doc(cfg(feature = "webhook")))]
+#[cfg(feature = "webhook")]
+pub mod webhooks;
 
 pub use assistant::*;
 pub use assistant_stream::*;