Better Data

API Reference

Webhooks

Edit this page

Overview

Better Data supports two directions of webhook traffic:

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

Outbound webhook configuration is in active development. Contact support@betterdata.co for early access.

Configuring tenant webhooks (UI)

For product and integration settings where the UI is available:

  1. Open Admin → Integrations
  2. Add or edit a webhook: URL, events, and signing secret as documented by the provider

Workspace-scoped configuration typically requires organization administrator permissions in your workspace.

Stripe

Billing — POST /webhooks/stripe

Status: live

Handles Stripe subscription and invoice lifecycle for billing, plan feature access, and audit logging.

Verification: requests must include a valid stripe-signature header; otherwise 400.

Handled events (representative)

| Event | Effect | | --- | --- | | customer.subscription.created | Org billing record; plan feature access activated | | customer.subscription.updated | Plan changes, capability snapshot recomputed | | customer.subscription.deleted | Downgrade, capabilities revoked | | invoice.paid | Payment confirmed, audit log | | invoice.payment_failed | Failure recorded, ops alert |

Endpoint URL:

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

Set STRIPE_WEBHOOK_SECRET to your Stripe signing secret.

Additional Stripe-specific reference may also use tag-level routes in OpenAPI; treat the URL above as the source of truth for billing webhooks.

Square

Product and inventory sync

Status: route may exist but handler work is in progress. In current platform builds, POST /api/webhooks/square can respond with 501 Not Implemented (stub) while SquareWebhookHandler and related models are completed — confirm behavior in your environment before going live.

Implementation detail: when additional provider-specific inbound routes ship on api.betterdata.co, they should be listed here from the same operational source of truth (do not assume parity with the Square stub).

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

Contact support@betterdata.co for timelines beyond the stub response or early integration.

Shopify / Square (catalog sync) — same class of events for catalog and levels when inbound routes are enabled.

Outbound (planned)

Better Data will send outbound notifications when key domain events occur.

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 (expected): webhook endpoints at apps.betterdata.co/settings/webhooks with HMAC verification, retries with backoff, and per-event delivery logs. Outbound webhooks are in active development — contact support@betterdata.co for early access.

Federation webhooks (planned)

Commerce Gateway merchants may configure a webhookUrl for federation events; delivery is not fully implemented yet.

Security

Inbound webhooks are verified before processing.

  • Stripe billing: stripe-signature HMAC verification with your signing secret
  • Future inbound sources: HMAC-SHA256 in an x-betterdata-signature header (or equivalent) as implementations ship

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