Skip to main content

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}