Webhook setup

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

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.

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

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.

If your provider supports webhook signing secrets, copy the secret and save it in Settings → Payment Providers for the matching account.

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

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

Troubleshooting

Webhooks not arriving

Confirm the URL includes both organization ID and provider ID
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)
Check the provider dashboard for delivery errors

Invalid signature errors

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

Webhook Setup