Struct Hmac256Webhook 

pub struct Hmac256Webhook { /* private fields */ }

Available on crate feature hmac only.

A custom webhook builder using HMAC SHA256 verification of the request body.

Example

This sets up a webhook that expects a hex-encoded signature in the Signature-SHA256 header, and a Unix epoch timestamp in the Timestamp header that will be attached as a suffix to the body when calculating the signature:

use rocket_webhook::{WebhookError, webhooks::generic::Hmac256Webhook};

let my_webhook = Hmac256Webhook::builder()
    .secret("my-secret")
    .expected_signatures(|req| {
        req.headers()
            .get_one("Signature-SHA256")
            .and_then(|header| hex::decode(header).ok())
            .map(|header| vec![header])
    })
    .body_suffix(|req, (min_time, max_time)| {
        req.headers()
            .get_one("Timestamp")
            .filter(|time| time.parse::<u32>().is_ok_and(|t| t > min_time && t < max_time))
            .map(|time| time.as_bytes().to_vec())
            .ok_or_else(|| WebhookError::Timestamp("Missing/invalid Timestamp header".into()))
    })
    .build();

Implementations

impl Hmac256Webhook

pub fn builder() -> Hmac256WebhookBuilder

Create an instance of Hmac256Webhook using the builder syntax

Trait Implementations

impl Webhook for Hmac256Webhook

async fn validate_body( &self, req: &Request<'_>, body: impl AsyncRead + Unpin + Send + Sync, time_bounds: (u32, u32), ) -> Outcome<'_, Vec<u8>, WebhookError>

Read body and validate webhook. If the webhook uses a timestamp, verify that it is within the expected bounds (bounds are in unix epoch seconds).

fn validate_timestamp( &self, timestamp: &str, (min, max): (u32, u32), ) -> Outcome<'_, (), WebhookError>

Validate a timestamp against the given bounds. The default implementation assumes that it is in Unix epoch seconds, and returns a Bad Request error if it is invalid.

fn get_header<'r>( &self, req: &'r Request<'_>, name: &str, prefix: Option<&str>, ) -> Outcome<'_, &'r str, WebhookError>

Retrieve a header that’s expected for a webhook request. The default implementation looks for the header and returns a Bad Request error if it was not provided. It can also optionally strip a given prefix.

impl WebhookHmac for Hmac256Webhook

type MAC = CoreWrapper<HmacCore<CoreWrapper<CtVariableCoreWrapper<Sha256VarCore, UInt<UInt<UInt<UInt<UInt<UInt<UTerm, B1>, B0>, B0>, B0>, B0>, B0>, OidSha256>>>>

MAC algorithm (from the hmac crate) used to calculate the signature

fn secret_key(&self) -> &[u8]

Get the secret key used to sign the webhook

fn expected_signatures( &self, req: &Request<'_>, ) -> Outcome<'_, Vec<Vec<u8>>, WebhookError>

Get the expected signature(s) from the request. To obtain required headers, you can use the self.get_header() utility.

fn body_prefix( &self, req: &Request<'_>, time_bounds: (u32, u32), ) -> Outcome<'_, Option<Vec<u8>>, WebhookError>

Get an optional prefix to attach to the raw body when calculating the signature. Timestamps should be validated against the given bounds.

fn body_suffix( &self, req: &Request<'_>, time_bounds: (u32, u32), ) -> Outcome<'_, Option<Vec<u8>>, WebhookError>

Get an optional suffix to attach to the raw body when calculating the signature. Timestamps should be validated against the given bounds.

fn validate_with_hmac( &self, req: &Request<'_>, body: impl AsyncRead + Unpin + Send + Sync, time_bounds: (u32, u32), ) -> impl Future<Output = Outcome<'_, Vec<u8>, WebhookError>> + Send + Sync

where Self: Sync, Self::MAC: Sync,

Read the request body and verify the HMAC signature. Calculates the HMAC directly from the raw streamed body (with a prefix if configured).