Stripe webhook revenue events

Stripe webhooks turn payment activity into a reliable revenue event stream.

Checkout redirects are useful for user experience, but revenue analytics should be driven by webhook events. Stripe sends events when checkout completes, invoices are paid, subscriptions change, and refunds occur. AttribIQ turns supported Stripe events into a smaller revenue event vocabulary that reports can understand.

Native receiver endpoint

For direct Stripe delivery, configure a Stripe webhook endpoint:

https://api.attribiq.com/v1/integrations/stripe/webhook

Use the API hostname for your deployment if you are not using the hosted AttribIQ service.

The Stripe object must include attribiq_project_id metadata so AttribIQ can route the revenue event to the right project. attribiq_visitor_id and attribiq_session_id are the strongest attribution links.

If your workspace does not yet expose self-serve Stripe signing-secret settings, ask support or your deployment operator to configure the endpoint secret, or use a customer-owned relay that sends normalized events to the Payment API.

Start with a small event set

For the current native AttribIQ receiver, start conservatively:

• invoice.paid
• customer.subscription.deleted
• charge.refunded

This set covers paid invoices, cancellations, and refunds while avoiding setup-mode checkout sessions and broad subscription updates.

Add these events only after you confirm that their semantics match your billing model:

• checkout.session.completed
• customer.subscription.created
• customer.subscription.updated

checkout.session.completed is useful for checkout completions, but setup-mode Checkout Sessions should not become purchases. customer.subscription.updated can mean upgrade, downgrade, status change, metadata change, or another non-revenue update.

If your backend needs exact control over those distinctions, use a Payment API relay instead of sending those raw Stripe events directly to AttribIQ.

Signature and idempotency

Stripe signs each webhook event with the endpoint secret. AttribIQ verifies signatures when that secret is configured for the receiver.

Stripe may retry events. AttribIQ stores processed Stripe event IDs and ignores duplicates so repeated deliveries do not duplicate purchases, renewals, or refunds.

Normalize into revenue events

AttribIQ's native Stripe receiver maps supported Stripe events into normalized revenue event types:

The mapping should be explicit in code. Do not let every Stripe event become a new analytics event type. Reporting works better when event names are stable.

Current implementation note: broad Stripe events can be ambiguous. For example, customer.subscription.updated is not always an upgrade, and checkout.session.completed can represent setup-mode flows. Use the conservative event set first unless you have verified the mapping for your billing flow.

Extract attribution metadata

For the first checkout, attribution usually comes from checkout.session.metadata. For renewals and subscription lifecycle events, metadata should come from the Subscription. That is why passing attribution to Stripe Checkout copies the same identifiers into subscription_data.metadata.

The minimum fields are:

• attribiq_project_id
• attribiq_visitor_id
• attribiq_session_id

If those fields are missing, the revenue event can still be valid. Mark it as unattributed and keep it in totals.

Handle refunds and churn carefully

Refunds should subtract money from the source that received the original credit. Churn should be tied back to the subscription or customer history so teams can see whether a channel creates poor-fit customers.

This does not mean every source with churn is bad. It means the dashboard should show revenue quality, not just first purchase volume.

Operational checks

Before going live:

• Send test webhooks from Stripe.
• Confirm duplicate events do not double-count revenue.
• Confirm metadata appears on subscriptions.
• Confirm missing metadata becomes unattributed revenue.
• Confirm refunds reduce net revenue.

Once this is stable, read connect Stripe to AttribIQ for the full setup checklist and UTM revenue attribution to understand how campaign reporting uses normalized events.