> ## Documentation Index
> Fetch the complete documentation index at: https://betterdatainc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Note>
  Outbound webhook configuration is in active development.
  Contact [support@betterdata.co](mailto:support@betterdata.co) to join the early access list.
</Note>

***

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

<Warning>
  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.
</Warning>

***

### 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 |

<Note>
  Contact [support@betterdata.co](mailto:support@betterdata.co) if you need a timeline for Square inbound processing beyond the stub response.
</Note>

***

## 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

<Note>
  Outbound webhooks are in active development.
  Join the early access list: [support@betterdata.co](mailto:support@betterdata.co)
</Note>

***

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