Webhook

A webhook is an automated HTTP message a system sends to a URL the moment a qualifying event happens, so that one application can tell another that something changed without the second application having to ask. It is the difference between being notified the instant a payment fails and finding out only the next time you happen to check.

In a subscription business, webhooks are how the billing platform keeps the rest of the stack in step with events it is the first to know about: a new account, a successful renewal, a failed charge, a plan change, a cancellation. Instead of your own systems polling for changes on a timer, the platform pushes a small notification to an endpoint you register, your endpoint acknowledges it, and your workflows react. Because a notification is a signal rather than a guaranteed source of truth, the reliable pattern is to treat each webhook as a prompt that something changed, then confirm the authoritative state through the platform's API before you act on it.

Why webhooks matter for subscription businesses

Subscriptions generate events continuously, and most of them happen inside the billing system rather than inside your product. Without webhooks you either poll the platform constantly, which is wasteful and always a little stale, or you learn about changes too late to respond well. A failed renewal that your systems do not hear about for hours is a customer who keeps full access while their payment is broken, and a support team with no signal to reach out. Webhooks close that gap by delivering the event as it happens, which is what makes near real time reactions possible: provisioning access on a new subscription, revoking it on a cancellation, kicking off a Dunning sequence when a charge fails, or updating finance records when an invoice is paid. They are the connective tissue between Invoicing, Collections, and every downstream system that needs to stay in sync, from your application to your CRM to your data warehouse.

How to use webhooks to keep systems in sync

A webhook integration's job is to receive events reliably, confirm what actually happened, and let your systems react without drifting out of sync with the billing platform.

1. Register an endpoint: stand up a URL on your side that can accept HTTP POST requests, and configure it in the billing platform so qualifying events are delivered there. Many platforms let you register more than one endpoint and choose which event types each one receives.

2. Receive and acknowledge: when an event fires, the platform posts a notification to your endpoint. Respond quickly with a success status so the sender knows delivery worked, and do the heavy processing separately rather than making the sender wait.

3. Verify the sender: confirm each request genuinely came from the billing platform, using the platform's signature or authentication mechanism, before you trust the payload. An open endpoint that acts on any request it receives is a security hole.

4. Confirm the authoritative state: treat the payload as a signal that something changed, then call the platform's API to read the current, authoritative state of the account, subscription, or invoice before you act. This keeps you correct even when notifications arrive late, out of order, or more than once.

5. React idempotently: run your workflow (provision access, send an email, update finance) in a way that produces the same result if the same event is delivered twice, so retries and duplicates never double-charge, double-provision, or double-notify.

6. Handle failures and retries: expect that your endpoint will occasionally be down, and that senders will retry. Make delivery failures visible, and reconcile periodically against the API so a missed notification does not leave your systems permanently out of step.

Example webhook payload

A webhook notification is a small JSON message describing the event that fired. For example, when a new account is created, the platform posts an event body like this:

{

"id": "r3oplsj3zo7a",

"object_type": "account",

"site_id": "r23khg9b5kyb",

"event_type": "created",

"event_time": "2022-06-24T19:55:25Z",

"account_code": "verena"

}

The payload names what happened and which object it happened to, but it is still only a signal. Following the pattern above, your endpoint reads the identifiers here (for example the account code), then calls the API to confirm the account's current state before acting.

Common mistakes with webhooks

• Treating the webhook payload as the final source of truth instead of confirming the current state through the API, so a stale or out-of-order notification drives the wrong action.

• Not verifying that the request actually came from the billing platform, which leaves the endpoint open to spoofed or replayed events.

• Handling events non-idempotently, so a legitimate retry or a duplicate delivery double-provisions access, sends two emails, or double-posts to finance.

• Doing slow work (heavy processing, third-party calls) before acknowledging the request, so the endpoint times out and the platform marks the delivery as failed.

• Assuming every event will always arrive exactly once and in order, and building no reconciliation path for the ones that are delayed, retried, or dropped when the endpoint is down.

• Returning a success status before the work is safely recorded, so a crash mid-processing loses an event the sender now believes was handled.

Benefits and examples

• Reacts to billing events in near real time, so access is provisioned on signup and revoked on cancellation without a nightly batch or a manual step.

• Cuts wasteful polling, since the platform pushes changes as they happen instead of your systems repeatedly asking whether anything is new.

• Feeds recovery workflows immediately: a failed-payment event can trigger a Dunning sequence and a customer outreach the moment the charge declines.

• Keeps downstream systems in sync, pushing subscription and invoice changes into your application, CRM, analytics, and data warehouse as they occur.

• Confirming authoritative state through the API on each event keeps automated actions correct even when notifications arrive late, duplicated, or out of order.

Frequently asked questions

What is a webhook in subscription billing?

An automated HTTP message the billing platform sends to a URL the instant a qualifying event happens, such as a new account, a renewal, a failed payment, or a cancellation, so your own systems can react without polling for changes.

How is a webhook different from an API call? With an API call your system asks the platform for information when it wants it. With a webhook the platform tells your system as soon as something happens. They work best together: the webhook signals that something changed, and an API call confirms the authoritative current state before you act.

Why should I verify state through the API instead of trusting the webhook payload? Notifications can arrive late, out of order, or more than once, and a payload is a snapshot from the moment it was sent. Treating the webhook as a prompt to read the current state through the API keeps your actions correct even when delivery is imperfect.

What happens if my endpoint is down when an event fires? Senders typically retry failed deliveries for a period, so a brief outage usually recovers on its own. For anything longer, reconcile against the API so a missed notification does not leave your systems permanently out of sync.

Why do webhooks need to be idempotent? Because the same event can legitimately be delivered more than once through retries or duplicates. Handling events idempotently means processing the same event twice produces the same result, so you never double-charge, double-provision, or double-notify.