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

# Webhooks overview

> Get notified the instant a buyer's access to one of your promotions changes — and act on it from any tool you use.

A webhook is a notification Boble sends to your own server every time something meaningful happens on one of your promotions: a new sale, a cancellation, a renewal that failed, a subscription that ran out.

Instead of polling Boble or refreshing a dashboard, you give us one URL per promotion and we `POST` you a small JSON message the moment it happens.

## What you can do with them

A few examples of what creators wire on top of Boble webhooks:

<Columns cols={2}>
  <Card title="Notify your team on every new sale" icon="bell">
    A new buyer joins your `Pro membership` → an automatic message lands in your Discord or Slack channel with the buyer's name and the promotion.
  </Card>

  <Card title="Sync buyers to your email tool" icon="envelope">
    A new buyer → automatically added to your Mailchimp, Brevo or ConvertKit list and tagged with the promotion they bought.
  </Card>

  <Card title="Revoke access in external tools" icon="lock">
    A subscription is canceled → the buyer loses their VIP role on your Discord or your Notion access automatically.
  </Card>

  <Card title="Push every sale to a sheet" icon="table">
    Every sale ends up as a new row in your Google Sheets or Airtable for accounting and reporting.
  </Card>
</Columns>

## How it works in three steps

<Steps>
  <Step title="You configure one URL per promotion">
    From your creator dashboard, attach an HTTPS URL to a promotion. That URL is where Boble will deliver every event for that promotion.
  </Step>

  <Step title="Boble notifies you in real time">
    Every change of access on the promotion triggers an event. The same events fire whether the change came from a Stripe checkout, a Stripe renewal, a dunning failure, or a manual action on your side.
  </Step>

  <Step title="Your service reacts">
    Your server (or your Zapier / Make / n8n endpoint) receives the event and does whatever you want: notify, sync, revoke, log.
  </Step>
</Steps>

## What events you receive

| Event                           | When it fires                                             |
| ------------------------------- | --------------------------------------------------------- |
| `user_promotion.access_granted` | A buyer just gained access to one of your promotions.     |
| `user_promotion.canceled`       | A buyer's access has been canceled.                       |
| `user_promotion.expired`        | A subscription term ended and was not renewed.            |
| `user_promotion.suspended`      | A recurring payment failed and access is paused.          |
| `webhook.test`                  | A test event you triggered manually to verify your setup. |

Each event carries the buyer, the promotion, the timing, and the new status. The full payload of every event — with a real example — is documented in [Event types](/webhooks/event-types).

## Good to know

<Info>
  Webhooks are **best-effort**. If your endpoint is down or your service replies with an error, Boble does **not** retry automatically. The failed delivery is logged and you can replay it from your dashboard whenever you want.
</Info>

<Note>
  Your endpoint URL must use `https://` and resolve to a public host. Local and private network addresses are rejected.
</Note>

## Next

<Columns cols={2}>
  <Card title="Event types" icon="list" href="/webhooks/event-types">
    The full catalog of events, what each one means, and a real payload for each.
  </Card>

  <Card title="Payload structure" icon="braces" href="/webhooks/payload-structure">
    What every Boble webhook delivery looks like.
  </Card>
</Columns>