# How webhooks work

How Southbill delivers webhooks, retries, and how to configure endpoints.

# How webhooks work

Webhooks let Southbill notify your server whenever something happens on your account — a payment succeeds, an invoice is paid, a dispute is opened.

## Configure endpoints

**Dashboard → Developers → Webhooks → Add endpoint**

- `url` — must be HTTPS.
- `description` — free-form.
- `enabled_events` — pick the events you want. Use `*` for everything.
- `mode` — `test` or `live`. Test-mode endpoints only receive events from test keys.

On save Southbill returns a **signing secret** (`whsec_…`) — copy it now, it's shown only once.

## Delivery guarantees

- HTTP `POST` with `Content-Type: application/json`.
- 2xx = success. Any non-2xx (or timeout > 20 s) triggers **exponential backoff retries** for up to 72 hours (roughly 15 attempts).
- Delivery attempts are visible per-event under the endpoint.
- Events can arrive **out of order**. Use `data.id` + `type` for idempotency.

## Envelope

```json
{
  "id": "evt_01H…",
  "object": "event",
  "type": "checkout.session.completed",
  "created": 1735689600,
  "livemode": true,
  "data": {
    "object": { /* the resource — checkout session, invoice, charge, dispute, payout, … */ }
  }
}
```

The resource always lives at `data.object`. See **Event reference** for the exact shape per event type.

## Testing

- Use `sk_test_…` keys and a test-mode endpoint. Southbill test cards work end-to-end.
- The **Developers → Webhooks → Test** button sends a synthetic `ping.test` event.