Struct WebhookContext 

#[non_exhaustive]
pub struct WebhookContext {
    pub webhook_name: String,
    pub request_id: String,
    pub idempotency_key: Option<String>,
    /* private fields */
}

Context available to webhook handlers.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

webhook_name: String

request_id: String

idempotency_key: Option<String>

Implementations

impl WebhookContext

pub fn new( webhook_name: String, request_id: String, headers: HashMap<String, String>, db_pool: PgPool, http_client: CircuitBreakerClient, ) -> Self

Create a new webhook context.

pub fn with_transaction( webhook_name: String, request_id: String, headers: HashMap<String, String>, db_pool: PgPool, tx: Transaction<'static, Postgres>, http_client: CircuitBreakerClient, ) -> (Self, Arc<Mutex<Option<Transaction<'static, Postgres>>>>)

Build a webhook context that dispatches jobs and workflows on tx.

The runtime opens the transaction, owns the handle, and commits or rolls back based on the handler’s result. Anything the handler dispatches lands on the same connection, so failed webhooks don’t leave orphaned jobs behind.

pub fn is_transactional(&self) -> bool

Whether dispatches will participate in an enclosing transaction.

pub fn with_kv(self, kv: Arc<dyn KvHandle>) -> Self

Attach a KV store handle. Called by the runtime before handing the context to the handler.

pub fn kv(&self) -> Result<&dyn KvHandle>

Access the KV store.

pub fn with_idempotency_key(self, key: Option<String>) -> Self

Set idempotency key.

pub fn with_job_dispatch(self, dispatcher: Arc<dyn JobDispatch>) -> Self

Set job dispatcher.

pub fn with_workflow_dispatch( self, dispatcher: Arc<dyn WorkflowDispatch>, ) -> Self

Set workflow dispatcher.

pub fn with_env_provider(self, provider: Arc<dyn EnvProvider>) -> Self

Set environment provider.

pub fn db(&self) -> ForgeDb

Get database pool.

pub fn db_conn(&self) -> DbConn<'_>

Get a DbConn for use in shared helper functions.

In transactional mode, returns a transaction-backed handle. Outside a transaction, returns a pool-backed handle.

pub async fn conn(&self) -> Result<ForgeConn<'_>>

Acquire a connection compatible with sqlx compile-time checked macros.

In transactional mode, returns a guard over the active transaction so the handler’s queries participate in the same transaction as its dispatches. Outside a transaction, acquires a fresh pool connection.

pub fn http(&self) -> HttpClient

Get the HTTP client for external requests.

pub fn raw_http(&self) -> &Client

Get the raw reqwest client, bypassing circuit breaker execution.

pub fn set_http_timeout(&mut self, timeout: Option<Duration>)

pub fn header(&self, name: &str) -> Option<&str>

Get a request header value.

Header names are case-insensitive.

pub fn headers(&self) -> &HashMap<String, String>

Get all headers.

pub async fn dispatch_job<T: Serialize>( &self, job_type: &str, args: T, ) -> Result<Uuid>

Dispatch a background job for async processing.

This is the recommended way to handle webhook events:

1. Validate the webhook signature
2. Dispatch a job to process the event
3. Return 202 Accepted immediately

Arguments

• job_type - The registered name of the job type
• args - The arguments for the job (will be serialized to JSON)

Returns

The UUID of the dispatched job, or an error if dispatch is not available.

pub async fn dispatch<J: ForgeJob>(&self, args: J::Args) -> Result<Uuid>

Type-safe dispatch: resolves the job name from the type’s ForgeJob impl and serializes the args at the call site.

pub async fn start_workflow<T: Serialize>( &self, workflow_name: &str, input: T, ) -> Result<Uuid>

Start a workflow.

pub async fn start<W: ForgeWorkflow>(&self, input: W::Input) -> Result<Uuid>

Type-safe workflow start.

pub async fn cancel_job( &self, job_id: Uuid, reason: Option<String>, ) -> Result<bool>

Request cancellation for a job.

Trait Implementations

impl EnvAccess for WebhookContext

fn env_provider(&self) -> &dyn EnvProvider

fn env(&self, key: &str) -> Option<String>

fn env_or(&self, key: &str, default: &str) -> String

fn env_require(&self, key: &str) -> Result<String>

fn env_parse<T: FromStr>(&self, key: &str) -> Result<T>

where T::Err: Display,

fn env_parse_or<T: FromStr>(&self, key: &str, default: T) -> Result<T>

where T::Err: Display,

Returns the default when unset; errors only if the variable is set but unparseable.

fn env_contains(&self, key: &str) -> bool

impl HandlerContext for WebhookContext

fn db(&self) -> ForgeDb

Database handle with automatic db.query tracing spans.

fn db_conn(&self) -> DbConn<'_>

Unified connection handle for shared helper functions.