Clavem

Webhook

A webhook is an HTTP request that one system sends to a URL you control when an event happens, so your software hears about the event without having to ask for it repeatedly.

How it works

  1. You register a public HTTPS URL with the sender and choose the events you care about.
  2. When an event happens, the sender POSTs a JSON body with an event id, a type and the object that changed.
  3. Your endpoint checks the signature, so a stranger cannot fake events.
  4. Your endpoint returns a 2xx status quickly. Slow work happens afterwards.
  5. If you return an error or time out, the sender tries again later.

Three rules follow from how Stripe describes its webhooks, and they apply to most senders:

  • Verify against the raw body. The signature is computed over the exact bytes sent. A framework that parses and re-serializes the JSON breaks verification.
  • Expect duplicates. Stripe tells you to track event ids and skip ones you already processed.
  • Expect disorder. Stripe does not guarantee events arrive in the order they were generated. A invoice.paid can arrive before the event that created the subscription, so fetch the current object when you need certainty.

Signature check, tested

Stripe sends a Stripe-Signature header and a secret per endpoint that starts with whsec_. Only a valid v1 HMAC signature proves the request is genuine. This Node snippet, run with the stripe package, builds a test header, verifies it, and then shows what a changed body does:

const header = stripe.webhooks.generateTestHeaderString({ payload, secret });
// t=1795127269,v1=<hmac>
const event = stripe.webhooks.constructEvent(payload, header, secret);
// ok: evt_1 checkout.session.completed
stripe.webhooks.constructEvent(payload + ' ', header, secret);
// throws: No signatures found matching the expected signature for payload.

One extra space in the body is enough to fail. That is why the raw body matters.

Webhook versus polling

Polling asks “anything new?” every few minutes. It is simple, wastes requests and adds delay. A webhook pushes the change at once but needs a public endpoint, signature checking and duplicate handling. Many sellers use both: the webhook for speed, and a periodic fetch to repair anything missed.

How Clavem handles it

Clavem receives webhooks. It does not send them: outbound webhooks to your own systems are not offered. When you connect Stripe, Clavem registers an endpoint in your Stripe account at a private URL of the form https://clavem.io/api/stripe/hook/<id>, pinned to a fixed Stripe API version so payloads keep the shape Clavem reads, and subscribed to six events:

checkout.session.completed
checkout.session.async_payment_succeeded
invoice.paid
customer.subscription.updated
customer.subscription.deleted
charge.refunded

Clavem verifies each request against the endpoint’s signing secret and processes each event id once, so Stripe’s retries and your own replays are safe. If processing fails, it answers with an error so Stripe retries. Stripe deliveries that return 400 usually mean the signing secret changed. What each event does to a license is in Connecting Stripe. Making your own fulfilment code safe is covered in Stripe webhooks for license fulfilment and idempotency keys.

Questions

Is a webhook the same as an API call?

An API call is you asking another service for data. A webhook is the other service calling you when something changes. Many systems offer both, and a webhook usually carries only a summary you can refetch through the API.

What happens if my webhook endpoint is down?

The sender retries. Stripe's documentation says it keeps trying for up to three days with exponential back off in live mode. After that, you recover by fetching the missing objects through the API.

Sources

  1. Stripe Docs, Receive Stripe events in your webhook endpoint (checked November 2026)
  2. Stripe Docs, Resolve webhook signature verification errors (checked November 2026)