PaperTiger.WebhookDelivery (PaperTiger v1.0.2)

Copy Markdown View Source

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).

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
  • 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")

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

deliver_event(event_id, webhook_endpoint_id)

Delivers a webhook event to a specific endpoint.

deliver_event_sync(event_id, webhook_endpoint_id)

Delivers a webhook event synchronously, waiting for completion.

sign_payload(payload, secret)

Signs a payload using HMAC SHA256 (Stripe-compatible).

start_link(opts \\ [])

Starts the WebhookDelivery GenServer.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

deliver_event(event_id, webhook_endpoint_id)

@spec deliver_event(String.t(), String.t()) :: {:ok, reference()} | {:error, term()}

Delivers a webhook event to a specific endpoint.

This function queues the delivery asynchronously. Multiple calls with different webhook_endpoint_ids deliver to all endpoints.

Parameters

  • event_id - ID of the event to deliver (e.g., "evt_123")
  • webhook_endpoint_id - ID of the webhook endpoint (e.g., "we_456")

Returns

  • {:ok, reference} - Delivery queued successfully
  • {:error, reason} - Delivery could not be queued

Examples

{:ok, _ref} = PaperTiger.WebhookDelivery.deliver_event("evt_123", "we_456")

deliver_event_sync(event_id, webhook_endpoint_id)

@spec deliver_event_sync(String.t(), String.t()) ::
  {:ok, :delivered | :failed} | {:error, term()}

Delivers a webhook event synchronously, waiting for completion.

Unlike deliver_event/2, this function blocks until the webhook has been delivered (or fails after all retries). Use this in test environments where you need webhooks to be processed before assertions.

Parameters

  • event_id - ID of the event to deliver (e.g., "evt_123")
  • webhook_endpoint_id - ID of the webhook endpoint (e.g., "we_456")

Returns

  • {:ok, :delivered} - Webhook delivered successfully
  • {:ok, :failed} - Delivery failed after all retries
  • {:error, reason} - Event or webhook not found

Examples

{:ok, :delivered} = PaperTiger.WebhookDelivery.deliver_event_sync("evt_123", "we_456")

sign_payload(payload, secret)

@spec sign_payload(String.t(), String.t()) :: String.t()

Signs a payload using HMAC SHA256 (Stripe-compatible).

Creates the signature component for the Stripe-Signature header. The actual signature is computed on "{timestamp}.{payload}".

Parameters

  • payload - JSON string (or any string data) to sign
  • secret - Webhook secret from the webhook endpoint

Returns

String containing the hex-encoded HMAC SHA256 signature.

Examples

signature = PaperTiger.WebhookDelivery.sign_payload(payload, "whsec_...")
# Returns: "abcd1234..."

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the WebhookDelivery GenServer.