feat: webhooks (#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

Author: 64bit

async-openai/Cargo.toml

@@ -25,6 +25,7 @@ native-tls-vendored = ["reqwest/native-tls-vendored"]
 realtime = ["dep:tokio-tungstenite"]
 # Bring your own types
 byot = []
+webhook = ["dep:hmac", "dep:sha2", "dep:hex"]
 
 [dependencies]
 async-openai-macros = { path = "../async-openai-macros", version = "0.1.0" }
@@ -50,6 +51,9 @@ secrecy = { version = "0.10.3", features = ["serde"] }
 bytes = "1.9.0"
 eventsource-stream = "0.2.3"
 tokio-tungstenite = { version = "0.26.1", optional = true, default-features = false }
+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 }
 
 [dev-dependencies]
 tokio-test = "0.4.4"

async-openai/README.md

@@ -68,6 +68,10 @@ $Env:OPENAI_API_KEY='sk-...'
 
 Only types for Realtime API are implemented, and can be enabled with feature flag `realtime`.
 
+## 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::{types::CreateEmbeddingRequestArgs, Client};
 

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::*;