Manages webhook event delivery to registered endpoints.

This GenServer delivers webhook events with:

• Stripe-compatible HMAC SHA256 signing of payloads
• Exponential backoff retry logic (max 5 attempts)
• Detailed delivery attempt tracking in Event object
• Concurrent delivery to multiple endpoints
• Optional synchronous mode for testing

Delivery Modes

By default, webhooks are delivered asynchronously. For testing, you can enable synchronous mode so API calls block until webhooks are delivered:

config :paper_tiger, webhook_mode: :sync

In sync mode, deliver_event_sync/2 is used which blocks until the webhook is delivered (or fails after all retries).

Delivery adapter (host-owned delivery)

How and where the signed request is sent is a pluggable PaperTiger.WebhookDelivery.Adapter:

config :paper_tiger, webhook_delivery_adapter: MyApp.WebhookSink

The default is PaperTiger.WebhookDelivery.HTTPAdapter, which performs the HTTP POST itself (historical behavior). A host embedding PaperTiger implements the behaviour to take durable ownership of delivery — persist the webhook so it survives restarts, then deliver/retry on its own schedule. The adapter contract ({:ok, %Response{}} = terminal success / ownership taken; {:error, reason} = PaperTiger retries) is explicit and enforced by a real function return, so a missing or crashing host cannot silently drop webhooks. See PaperTiger.WebhookDelivery.Adapter.

This is separate from :webhook_mode (:sync/:async/:collect), which controls when delivery is dispatched, not where it goes.

Telemetry

[:paper_tiger, :webhook, :delivering] is emitted for every delivery, in every adapter, immediately after the payload is signed and the headers are built and immediately before the adapter is called.

• measurements: %{system_time: System.system_time()}
• metadata: %{event: map, webhook: map, url: String.t(), payload: String.t(), headers: [{String.t(), String.t()}], signature_header: String.t(), timestamp: integer(), namespace: term()}

This event is observability only — it is not the delivery mechanism. Delivery handoff is the Adapter behaviour. Use this event for metrics and tracing, not for correctness-critical work.

Architecture

• Async delivery: deliver_event/2 - Queues a delivery task (default)
• Sync delivery: deliver_event_sync/2 - Blocks until complete
• Signing: sign_payload/2 - Creates Stripe-compatible HMAC SHA256 signature
• Signed request construction: build_signed_request/3 - Produces the exact raw body, Stripe-Signature header, and HTTP headers without delivering the webhook
• HTTP client: Uses Req library for reliable, timeout-aware requests
• Retry strategy: Exponential backoff (1s, 2s, 4s, 8s, 16s)
• Tracking: Stores delivery attempts in Event object via Store.Events

Stripe Signature Format

The Stripe-Signature header follows Stripe's format:

Stripe-Signature: t={timestamp},v1={signature}

Where:

• t = Unix timestamp when webhook was created
• v1 = HMAC SHA256 signature of "{timestamp}.{payload}" using webhook secret

Examples

# Deliver an event asynchronously (default)
{:ok, _ref} = PaperTiger.WebhookDelivery.deliver_event("evt_123", "we_456")

# Deliver an event synchronously (for testing)
{:ok, :delivered} = PaperTiger.WebhookDelivery.deliver_event_sync("evt_123", "we_456")

# Manually create a signature for testing
signature = PaperTiger.WebhookDelivery.sign_payload("body", "secret")

# Build the exact webhook request a controller test should verify
request = PaperTiger.WebhookDelivery.build_signed_request(event, webhook)