# Webhook Setup (https://docs.billwave.example/getting-started/webhook-setup)

Webhook setup [#webhook-setup]

Billwave receives provider webhooks on your behalf. This keeps subscriptions, entitlements, and usage in sync.

<Callout type="info">
  **Sandbox needs no setup.** Sandbox payments run on provider accounts that
  Billwave manages, and their webhooks already point at Billwave. The steps
  below are for **live**, or for a sandbox account you added yourself.
</Callout>

1. Find your webhook URL [#1-find-your-webhook-url]

Your webhook URL is:

```
https://api.billwave.example/webhooks/{your-organization-id}/{provider-id}
```

Example:

```
https://api.billwave.example/webhooks/org_123/{provider-id}
```

2. Configure your provider [#2-configure-your-provider]

In your provider dashboard, paste the webhook URL and save. If you brought your own sandbox account, configure it on the provider's test environment and use `https://sandbox.billwave.example` as the host instead.

<Callout type="important">
  If your provider supports webhook signing secrets, copy the secret and save it
  in **Settings → Payment Providers** for the matching account.
</Callout>

3. Verify delivery [#3-verify-delivery]

Trigger a test payment or subscription in your provider dashboard. You should see:

* A subscription appear in the Billwave dashboard
* An event logged in the **Events** tab

Common events Billwave handles [#common-events-billwave-handles]

* Subscription created, updated, canceled
* Payment succeeded or failed
* Refunds (when supported by the provider)

Troubleshooting [#troubleshooting]

Webhooks not arriving [#webhooks-not-arriving]

1. Confirm the URL includes both organization ID and provider ID
2. Confirm the provider account environment matches your test/live setup, and that the host matches (`api.billwave.example` for live, `sandbox.billwave.example` for your own sandbox account)
3. Check the provider dashboard for delivery errors

Invalid signature errors [#invalid-signature-errors]

1. Confirm the saved webhook secret matches the provider account
2. Ensure you pasted the secret without whitespace
3. Regenerate the secret and save it again