scyph_utils/webhook/error.rs
1//! Webhook error types.
2//!
3//! Defines [`WebhookError`] — all failures that can occur during HMAC-SHA256 webhook signature
4//! verification. These map to HTTP client errors (`400 Bad Request`) since they indicate that
5//! the incoming request is malformed or untrusted, not a server-side infrastructure failure.
6
7use scyph_core::AppError;
8
9/// Errors encountered during webhook signature verification.
10///
11/// ## HTTP Mapping
12///
13/// | Variant | HTTP Status | Meaning |
14/// |---------|-------------|---------|
15/// | `StaleTimestamp` | 400 | Webhook delivered too late (replay protection) |
16/// | `SignatureMismatch` | 400 | Wrong secret or tampered payload |
17/// | `InvalidHeaderFormat` | 400 | Malformed signature header |
18/// | `HmacKey` | 500 | Bad HMAC key configuration (server fault) |
19///
20/// # Examples
21///
22/// ```rust
23/// use scyph_utils::webhook::WebhookError;
24///
25/// let err = WebhookError::SignatureMismatch;
26/// assert_eq!(err.to_string(), "Invalid webhook signature");
27///
28/// let err = WebhookError::StaleTimestamp { tolerance_secs: 300, delta_secs: 450 };
29/// assert!(err.to_string().contains("450s"));
30/// ```
31#[derive(Debug, thiserror::Error)]
32pub enum WebhookError {
33 /// Webhook timestamp is outside permitted tolerance window.
34 #[error("Stale webhook timestamp: delta {delta_secs}s exceeds tolerance {tolerance_secs}s")]
35 StaleTimestamp {
36 /// Configured tolerance threshold in seconds.
37 tolerance_secs: i64,
38 /// Actual difference between server time and webhook timestamp.
39 delta_secs: i64,
40 },
41
42 /// HMAC webhook signature verification mismatch.
43 #[error("Invalid webhook signature")]
44 SignatureMismatch,
45
46 /// Malformed or invalid webhook signature header format.
47 #[error("Invalid webhook header format: {0}")]
48 InvalidHeaderFormat(String),
49
50 /// Key initialization error for HMAC cryptography.
51 #[error("HMAC secret key error: {0}")]
52 HmacKey(String),
53}
54
55impl From<WebhookError> for AppError {
56 fn from(err: WebhookError) -> Self {
57 match err {
58 WebhookError::StaleTimestamp { .. }
59 | WebhookError::SignatureMismatch
60 | WebhookError::InvalidHeaderFormat(_) => AppError::BadRequest(err.to_string()),
61 WebhookError::HmacKey(msg) => AppError::internal(msg),
62 }
63 }
64}