Webhook Processing

Flow

Receive

Stripe sends webhook to billing service endpoint.

Validate

HMAC signature verified. Webhook record created with status PENDING.

Deduplicate

Check unique constraint (provider, externalRef) to prevent duplicate processing.

Process

Status → PROCESSING. Event type dispatched to appropriate handler.

Complete

Status → PROCESSED on success, FAILED on error (with retry).

Stripe Event	Action
`invoice.paid`	Update invoice status to PAID
`invoice.payment_failed`	Update invoice, set subscription to PAST_DUE
`invoice.finalized`	Create/update invoice record
`charge.refunded`	Update invoice to REFUNDED
`charge.dispute.created`	Update invoice to DISPUTED

Failed webhooks increment attempts and can be retried. Max 3 attempts with exponential backoff.

⌘I