Webhooks

Receive real-time event notifications — and send data into Better Data from external platforms.

Overview

Better Data supports two directions of webhook traffic:

• Inbound webhooks — external platforms (Stripe, Shopify) notify Better Data of events
• Outbound webhooks — Better Data notifies your systems when domain events occur (planned)

Outbound webhook configuration is in active development. Contact [e-mail] to join the early access list.

---

Inbound Webhooks

Stripe Billing POST /webhooks/stripe

Status: Live (handler: apps/cco-api/app/webhooks/stripe/route.ts in bd-forge-main)

Handles Stripe subscription and invoice lifecycle events. Used for billing updates, entitlement recomputation, and audit logging.

Verification

All requests are verified using the stripe-signature header. Requests without a valid signature are rejected with 400.

Handled events

Event	What happens
customer.subscription.created	Org billing record created, entitlements provisioned
customer.subscription.updated	Plan change applied, TenantCapabilitySnapshot recomputed
customer.subscription.deleted	Org downgraded, capabilities revoked
invoice.paid	Payment confirmed, billing audit log written
invoice.payment_failed	Payment failure recorded, ops alert triggered

Setup

Configure your Stripe webhook to point to:

https://api.betterdata.co/webhooks/stripe

Set the STRIPE_WEBHOOK_SECRET environment variable to your Stripe signing secret.

Canonical billing webhook path is /webhooks/stripe (mounted on the cco-api deployment at e.g. https://api.betterdata.co) — not /api/webhooks/stripe.

There is a separate route file at apps/cco-api/app/api/webhooks/stripe/route.ts that intentionally responds with 501 Not Implemented (stub). Stripe must not be pointed at that path in production.

---

Square (catalog / inventory webhooks)

Status: Route exists; implementation not live — POST /api/webhooks/square (apps/cco-api/app/api/webhooks/square/route.ts) currently returns 501 with a JSON error body indicating SquareWebhookHandler / related models are incomplete (see inline comment in that file).

Implementation detail pending verification: when Shopify or other provider-specific inbound routes are added under apps/cco-api, list them here from the same codebase scan (do not assume parity with this Square stub).

Planned event families (doc-level)	Intended effect
Product lifecycle	Catalog alignment when handler is complete
Inventory updates	Stock level alignment when handler is complete

Contact [e-mail] if you need a timeline for Square inbound processing beyond the stub response.

---

Outbound Webhooks (Planned)

Better Data will send outbound webhook notifications when key domain events occur in your loops.

Planned event coverage

Category	Events
Loop transitions	Any loop state change (procurement, orders, returns, quality)
Import	import.completed, import.partial, import.failed
Allocation	order.allocation_failed, order.allocation_succeeded
Demand	demand_signal.spike_detected, demand_signal.stockout_risk
Billing	subscription.updated, loop_commitment.threshold_reached

Configuration

Webhook endpoints will be configurable at: apps.betterdata.co/settings/webhooks

Delivery will include:

• HMAC signature verification
• Retry with exponential backoff
• Delivery log with per-event status

Outbound webhooks are in active development. Join the early access list: [e-mail]

---

Federation Webhooks (Planned)

Commerce Gateway merchants can configure a webhookUrl to receive federation events. Delivery is not yet implemented.

---

Webhook Security

All inbound webhooks verify request authenticity before processing.

Stripe: stripe-signature HMAC verification using your webhook signing secret.

Future inbound sources: HMAC-SHA256 signature in x-betterdata-signature header (implementation in progress).

Never expose webhook secrets in client-side code or public repositories.