# OpenMeter Webhooks

OpenMeter (usage metering and billing, now part of Kong) sends **notifications**
to webhook **channels** when a notification **rule** matches, for example when a
customer crosses 80% of an entitlement or an invoice changes state. Delivery
uses Svix, so OpenMeter webhooks are verified like any Svix webhook.

## When to Use This Skill

* How do I receive OpenMeter webhooks?
* How do I verify OpenMeter webhook signatures?
* Why is my OpenMeter webhook signature verification failing?
* How do I handle `entitlements.balance.threshold` usage alerts?
* How do I react to `entitlements.reset`, `invoice.created`, or `invoice.updated`?
* Where do I find (or set) the signing secret for an OpenMeter notification channel?

## Verification (core)

Each request carries `svix-id`, `svix-timestamp` (Unix seconds) and
`svix-signature` (space-delimited `v1,<base64>` entries). The signature is
base64 HMAC-SHA256 over `${svix-id}.${svix-timestamp}.${raw_body}`, keyed with
the base64-decoded secret after the optional `whsec_` prefix. OpenMeter's own
docs use the official `svix` SDK, which also checks a 5-minute timestamp
tolerance and compares in constant time:

```javascript
import { Webhook } from 'svix'; // svix 2.x is ESM-only

const wh = new Webhook(process.env.OPENMETER_WEBHOOK_SECRET); // "whsec_..."
wh.verify(rawBody, {                 // rawBody: the raw request body, NOT parsed JSON
  'svix-id': req.headers['svix-id'],
  'svix-timestamp': req.headers['svix-timestamp'],
  'svix-signature': req.headers['svix-signature'],
}); // throws WebhookVerificationError on a bad signature or stale timestamp
const event = JSON.parse(rawBody);   // { id, timestamp, type, data }

```

Python uses the same SDK: `from svix.webhooks import Webhook` and
`Webhook(secret).verify(raw_body, headers)`.

> **Custom secrets:** if you set your own `signingSecret` on the channel, keep the
> `whsec_` prefix (e.g. `whsec_<base64>`). OpenMeter accepts it without the prefix,
> but Svix/Standard Webhooks libraries and Hookdeck rely on the prefix to know the
> rest is base64 and must be decoded before use as the HMAC key.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/openmeter-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/openmeter-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/openmeter-webhooks/examples/fastapi/).

## Common Event Types

| Event | Fires When |
| --- | --- |
| `entitlements.balance.threshold` | A metered entitlement's usage crosses a rule threshold (percent or absolute) |
| `entitlements.reset` | A metered entitlement is reset, manually or at the end of its usage period |
| `invoice.created` | A new invoice is generated (gathering invoices excluded) |
| `invoice.updated` | An existing invoice changes state (e.g. `draft.created` → `draft.sync`) |

Every payload is an envelope: `{ "id", "timestamp", "type", "data" }`. Use
`id` (or the `svix-id` header) for idempotency.

> **For full event reference**, see [OpenMeter notification rules](https://openmeter.io/docs/integrations/notifications/rule).

## Environment Variables

```bash
OPENMETER_WEBHOOK_SECRET=whsec_xxxxx   # Notification channel signing secret

```

## Local Development

For local webhook testing, run the Hookdeck CLI via `npx` (no install, no account required):

```bash
npx hookdeck-cli listen 3000 openmeter --path /webhooks/openmeter

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/openmeter-webhooks/references/overview.md) - Notification channels, rules, events and payloads
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/openmeter-webhooks/references/setup.md) - Create a webhook channel and rule, get the signing secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/openmeter-webhooks/references/verification.md) - Signature verification details and gotchas
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/openmeter-webhooks/examples/) - Runnable Express, Next.js and FastAPI handlers with tests