Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! HTTP webhook validation client.
#[cfg(test)]
#[path = "http_validator_test.rs"]
mod http_validator_test;
use crate::domain::{
models::{
Webhook, WebhookEndpointSchemePolicy, WebhookValidationResult, WebhookValidationTestEvent,
},
ports::WebhookValidationClient,
};
use reqwest::{Client, StatusCode, Url, redirect::Policy};
use std::{net::IpAddr, time::Duration};
use tokio::net::lookup_host;
const EVENT_NAME: &str = "webhook.validation.test";
pub(super) const REQUEST_TIMEOUT: Duration = Duration::from_secs(5);
/// Reqwest-backed implementation of [`WebhookValidationClient`].
#[derive(Clone)]
pub struct ReqwestWebhookValidationClient {
pub(super) client: Client,
pub(super) endpoint_scheme_policy: WebhookEndpointSchemePolicy,
}
impl ReqwestWebhookValidationClient {
/// Create a validation client that requires public HTTPS endpoints.
pub fn new() -> Result<Self, reqwest::Error> {
Self::new_with_endpoint_scheme_policy(WebhookEndpointSchemePolicy::HttpsOnly)
}
/// Create a validation client with an explicit endpoint policy.
pub fn new_with_endpoint_scheme_policy(
endpoint_scheme_policy: WebhookEndpointSchemePolicy,
) -> Result<Self, reqwest::Error> {
let client = Client::builder()
.timeout(REQUEST_TIMEOUT)
.redirect(Policy::none())
.build()?;
Ok(Self {
client,
endpoint_scheme_policy,
})
}
}
impl WebhookValidationClient for ReqwestWebhookValidationClient {
type Err = anyhow::Error;
async fn validate_webhook(
&self,
webhook: Webhook,
) -> Result<WebhookValidationResult, Self::Err> {
let url = match validate_resolved_endpoint_url(
&webhook.endpoint_url,
self.endpoint_scheme_policy,
)
.await
{
Ok(url) => url,
Err(error) => return Ok(failure(None, error.message())),
};
let event_id = new_validation_event_id();
let timestamp = chrono::Utc::now().timestamp().to_string();
let body = validation_body(&webhook.id, &event_id)?;
let signature = signature_header(&webhook.signing_secret, ×tamp, &body)?;
let mut request = self
.client
.post(url)
.header(reqwest::header::CONTENT_TYPE, "application/json")
.header("X-Macro-Event", EVENT_NAME)
.header("X-Macro-Event-Id", event_id)
.header("X-Macro-Timestamp", ×tamp)
.header("X-Macro-Signature", signature);
for (name, value) in webhook.headers {
if is_reserved_macro_header(&name) {
return Ok(failure(None, "reserved Macro headers cannot be overridden"));
}
request = request.header(name, value);
}
let response = match request.body(body).send().await {
Ok(response) => response,
Err(error) if error.is_timeout() => {
return Ok(failure(None, "validation timed out after 5 seconds"));
}
Err(_) => return Ok(failure(None, "webhook endpoint could not be reached")),
};
let status = response.status();
if status.is_success() {
return Ok(WebhookValidationResult {
is_valid: true,
response_status: Some(status.as_u16()),
message: None,
});
}
Ok(failure(
Some(status),
format!("webhook returned HTTP {}", status.as_u16()),
))
}
}
fn new_validation_event_id() -> String {
format!("evt_{}", macro_uuid::generate_uuid_v7())
}
fn validation_body(webhook_id: &str, event_id: &str) -> Result<Vec<u8>, serde_json::Error> {
serde_json::to_vec(&WebhookValidationTestEvent {
id: event_id.to_owned(),
event: EVENT_NAME.to_owned(),
webhook_id: webhook_id.to_owned(),
})
}
pub(super) fn signature_header(
secret: &str,
timestamp: &str,
raw_body: &[u8],
) -> Result<String, anyhow::Error> {
webhook_signature::sign(secret, timestamp, raw_body)
.ok_or_else(|| anyhow::anyhow!("failed to key the delivery signature"))
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(super) enum EndpointValidationError {
InvalidConfiguration(&'static str),
ResolutionFailure(&'static str),
}
impl EndpointValidationError {
pub(super) const fn message(self) -> &'static str {
match self {
Self::InvalidConfiguration(message) | Self::ResolutionFailure(message) => message,
}
}
pub(super) const fn is_retryable(self) -> bool {
matches!(self, Self::ResolutionFailure(_))
}
}
pub(super) async fn validate_resolved_endpoint_url(
value: &str,
endpoint_scheme_policy: WebhookEndpointSchemePolicy,
) -> Result<Url, EndpointValidationError> {
let url = validate_endpoint_url(value, endpoint_scheme_policy)?;
let Some(host) = url.host_str().map(str::to_owned) else {
return Err(EndpointValidationError::InvalidConfiguration(
"webhook endpoint URL host is invalid",
));
};
let Some(port) = url.port_or_known_default() else {
return Err(EndpointValidationError::InvalidConfiguration(
"webhook endpoint URL port is invalid",
));
};
let mut resolved =
match tokio::time::timeout(REQUEST_TIMEOUT, lookup_host((host.as_str(), port))).await {
Ok(Ok(resolved)) => resolved,
Ok(Err(_)) => {
return Err(EndpointValidationError::ResolutionFailure(
"webhook endpoint host could not be resolved",
));
}
Err(_) => {
return Err(EndpointValidationError::ResolutionFailure(
"webhook endpoint host resolution timed out",
));
}
};
let mut saw_address = false;
for address in resolved.by_ref() {
saw_address = true;
if !endpoint_scheme_policy.allows_local_addresses() && is_blocked_ip(address.ip()) {
return Err(EndpointValidationError::InvalidConfiguration(
"webhook endpoint host resolves to a disallowed address",
));
}
}
if !saw_address {
return Err(EndpointValidationError::ResolutionFailure(
"webhook endpoint host could not be resolved",
));
}
Ok(url)
}
fn validate_endpoint_url(
value: &str,
endpoint_scheme_policy: WebhookEndpointSchemePolicy,
) -> Result<Url, EndpointValidationError> {
let url = Url::parse(value).map_err(|_| {
EndpointValidationError::InvalidConfiguration("webhook endpoint URL is invalid")
})?;
if !endpoint_scheme_policy.allows(url.scheme()) {
return Err(EndpointValidationError::InvalidConfiguration(
"webhook endpoint URL must use HTTPS",
));
}
let Some(host) = url.host_str() else {
return Err(EndpointValidationError::InvalidConfiguration(
"webhook endpoint URL host is invalid",
));
};
if !endpoint_scheme_policy.allows_local_addresses() && is_blocked_host(host) {
return Err(EndpointValidationError::InvalidConfiguration(
"webhook endpoint host is not allowed",
));
}
Ok(url)
}
fn is_blocked_host(host: &str) -> bool {
let host = host.trim_matches(['[', ']']).to_ascii_lowercase();
if host == "localhost" || host.ends_with(".localhost") {
return true;
}
host.parse::<IpAddr>().is_ok_and(is_blocked_ip)
}
fn is_blocked_ip(ip: IpAddr) -> bool {
match ip {
IpAddr::V4(ip) => {
ip.is_private()
|| ip.is_loopback()
|| ip.is_link_local()
|| ip.is_broadcast()
|| ip.is_unspecified()
|| ip.octets() == [169, 254, 169, 254]
}
IpAddr::V6(ip) => {
ip.is_loopback()
|| ip.is_unspecified()
|| ip.is_unique_local()
|| (ip.segments()[0] & 0xffc0) == 0xfe80
}
}
}
pub(super) fn is_reserved_macro_header(name: &str) -> bool {
matches!(
name.to_ascii_lowercase().as_str(),
"x-macro-event" | "x-macro-event-id" | "x-macro-timestamp" | "x-macro-signature"
)
}
fn failure(status: Option<StatusCode>, message: impl Into<String>) -> WebhookValidationResult {
WebhookValidationResult {
is_valid: false,
response_status: status.map(|status| status.as_u16()),
message: Some(message.into()),
}
}