Skip to main content

Module webhook_delivery

rustango

Module webhook_delivery 

Source
Expand description

Outbound webhook delivery — POSTs HMAC-signed JSON via the background job queue (so retries with exponential backoff are free). See webhook_delivery::WebhookSubscription. Outbound webhook delivery — POSTs an HMAC-signed JSON payload to a subscriber URL via the background job queue.

Wraps the existing crate::webhook signing format and the crate::jobs retry-with-backoff machinery into a one-call API:

ⓘ
use rustango::webhook::SignatureFormat;
use rustango::webhook_delivery::WebhookSubscription;

// Once per app — register the delivery handler.
WebhookSubscription::register(&queue).await;

// Per outbound event:
WebhookSubscription::new(
        "https://customer.example.com/hooks",
        "shared-secret-32-bytes",
    )
    .signature_format(SignatureFormat::HexSha256WithPrefix)
    .header("X-Tenant-Id", "acme")
    .dispatch(&queue, "order.created", &serde_json::json!({"order_id": 42}))
    .await?;

§What gets sent

  • POST <target_url>
  • Body: the payload re-serialized to JSON.
  • Content-Type: application/json
  • User-Agent: rustango-webhook/<crate version>
  • X-Webhook-Id: <uuid> — stable per delivery, retried as-is so the receiver can dedup.
  • X-Webhook-Event: <event_name>
  • X-Webhook-Signature: <signature> (header + format follow your chosen [SignatureFormat]).
  • Any extra headers added via [WebhookSubscription::header].

§Retry policy

Status codes are mapped to job outcomes:

  • 2xx — success, delivery completes.
  • 408 Request Timeout / 429 Too Many Requests / 5xx — JobError::Retryable; retried with exponential backoff up to MAX_ATTEMPTS (default 8).
  • other 4xx — JobError::Fatal; goes straight to dead-letter, no retries (a malformed URL or auth failure won’t fix itself).
  • transport errors (connect refused, DNS failure, body too large, etc.) — JobError::Retryable.

Customize per-subscription with [WebhookSubscription::retry_status_codes].

Structs§

WebhookEvent
One outbound webhook event — the Job payload that the queue persists, retries, and eventually delivers (or dead-letters).
WebhookSubscription
Static config for one webhook subscriber, plus convenience methods to register the delivery handler and dispatch events.

Constants§

HEADER_EVENT
Header that carries the event name.
HEADER_ID
Header that carries the per-delivery UUID — receivers can dedup on it.
HEADER_SIGNATURE
Header that carries the HMAC signature of the body.

Statics§

USER_AGENT
User-Agent advertised on every delivery.

Type Aliases§

SharedSubscription