Webhook events

MonetizeIt delivers events to your HTTPS endpoints so your billing, CRM and automation stay in sync without polling. The contract follows two open standards: the payload is a CloudEvents 1.0 envelope, and delivery is signed per Standard Webhooks.

Subscribing

Create a subscription from the portal’s Webhooks page or the admin API:

POST /api/v1/webhooks/admin/subscriptions — register an endpoint URL, the event types you want, an optional filter, and a signing secret.
GET /api/v1/webhooks/admin/subscriptions · GET | PATCH | DELETE …/{id} — manage them.
POST …/{id}/test-fire — send a sample event to your endpoint.

Every event type the platform emits is discoverable, unauthenticated, at GET /api/v1/webhooks/schemas.

Patterns and filters

A subscription matches event types exactly (Entitlement.Activated), by prefix wildcard (Entitlement.*), or all (*). You can narrow further by entity kind (entitlement, asset-usage-tracker, …), by severity (for overage events), and by attribute equality.

Registration challenge

When you create a subscription, MonetizeIt immediately POSTs a Webhooks.Registration.Challenge to your URL. Read data.challenge, sign it with your shared secret, and return that signature in the response body. The subscription becomes Active only once you echo back the correct signature — this proves you own the endpoint. Subscriptions move through PendingVerification → Active, and can later be Disabled or Suspended.

The envelope

Every delivery is a CloudEvents 1.0 JSON document:

{
  "specversion": "1.0",
  "id": "01J…",
  "source": "urn:monetizeit:…",
  "type": "Entitlement.Activated",
  "time": "2026-06-16T10:00:00Z",
  "subject": "…",
  "datacontenttype": "application/json",
  "entitykind": "entitlement",
  "entityid": "…",
  "eventversion": 1,
  "data": { }
}

data is event-specific and non-strict — ignore fields you don’t recognise, so new ones never break you.

Verifying a delivery

Each request carries the Standard Webhooks headers:

Header	Meaning
`webhook-id`	The envelope id
`webhook-timestamp`	RFC 3339 UTC send time
`webhook-signature`	`v1,` + base64 HMAC-SHA256
`webhook-event-type`	e.g. `Entitlement.Activated`
`webhook-delivery-attempt`	Retry counter
`webhook-callback-token`	Optional short-lived JWT (see below)

Recompute the signature over {webhook-id}.{webhook-timestamp}.{raw-body} and compare in constant time:

signature = "v1," + base64( HMAC_SHA256(secret, id + "." + timestamp + "." + body) )

Reject anything that doesn’t match, or whose timestamp is too old to trust.

Secret rotation

During a rotation there is an overlap window: MonetizeIt sends both signatures, space-separated, in webhook-signature. Accept the delivery if either verifies, so you can roll keys with no dropped events.

Calling back

If your subscription requests callback scopes, each delivery includes a short-lived JWT in webhook-callback-token. Use it as a bearer token to call straight back into the admin API with exactly those scopes — no separate OAuth round-trip. Only read / create / update / write verbs are allowed; delete and wildcards are not.

Delivery and retries

Delivery is at-least-once and idempotent — deduplicate on webhook-id. Failed deliveries (5xx, timeout, DNS) retry with exponential backoff; once retries are exhausted the delivery is recorded as failed and kept for inspection, and every attempt is audited.

Event catalog

Event type	Fires when
`Entitlement.Activated`	A license is activated
`Entitlement.Expiring`	An entitlement is approaching expiry
`Entitlement.TrialExpiring`	A trial is approaching its end
`Entitlement.Renewed`	A subscription period renews
`Entitlement.Cancelled`	An entitlement is cancelled
`Entitlement.PlanApplied`	A usage plan is applied or changed
`MeteredUsage.OverageStatusChanged`	A metered asset crosses a tier (`Normal` / `Warning` / `Critical` / `OverUsage`)
`DataSubjectRequest.Filed` · `.Approved` · `.Rejected` · `.Completed`	A data-subject request changes state
`User.Erased`	A user is erased
`Webhooks.Registration.Challenge`	Sent once, to verify a new subscription