Webhook events

Each webhook event KeyGrant sends: when it is sent, and what its data holds (see The request).

Common fields

These mean the same in every event that carries them. Times are in Unix milliseconds.

License events

license.issued

Sent when

Issued in the dashboard or over the API, imported, or sold through a Stripe or Paddle checkout.

Data

Common fields: key, product, email, and:

Notes

• Not sent when a checkout upgrades a key the customer already holds (license.upgraded is).

license.revoked

Sent when

A key was revoked, or its Stripe or Paddle subscription was canceled:

• By hand or over the API.
• By a full refund or a lost dispute (see Refunds and disputes).
• Its Stripe or Paddle subscription was canceled.
• Up to a day after a subscription key's grace period ends or a trial key expires.

Data

Common fields: key, product, and:

Notes

• A canceled subscription therefore sends it twice: once when it is canceled, and again when the key stops working.

license.reinstated

Sent when

In any of these cases:

• A subscription key that was canceled, or revoked after its grace period ran out, because Stripe or Paddle reports its subscription as paid. A key revoked by hand, by a refund or by a dispute is never reinstated this way.
• A refund that revoked a key fails or is canceled after Stripe took it (see A refund that fails); a failed refund never brings back a key revoked by hand or by a dispute.
• A chargeback Paddle reverses puts back the keys it revoked (see Selling through Paddle).
• You put a revoked key back by hand.

Data

Common fields: key, product, email, and:

license.upgraded

Sent when

A checkout upgraded a key the customer already holds, or an upgrade was put on a key afterwards:

• A version upgrade added versions (see Sell an upgrade).
• An edition upgrade changed its entitlements (see Sell an edition upgrade).
• A device upgrade raised its device limit (see Sell more devices).
• A top-up added uses to its meters (see Sell more uses).
• A timed model bought again extended its term, one event for each key of its purchase (see Timed models).
• You attached a held sale to a key (see Resolve a held sale).
• A refund that took an upgrade back failed, and the upgrade was put back on the key.

Data

Common fields: key, product, email, and:

license.upgrade_reverted

Sent when

A full refund or a lost dispute took such an upgrade back (see Refunds and disputes). The key stays active.

Data

license.flagged

Sent when

KeyGrant flags a purchase for you to look at (see Repeat refunds and duplicate purchases). The kind says why:

• repeat-refund: a checkout created a key whose buyer holds an earlier key of the same product, for the same major version, that a refund or a dispute took back.
• duplicate: a checkout created a key whose buyer holds an earlier key of the same product, for the same major version, bought under the same license model in the 7 days before.
• refunded-file: a refund, a lost dispute, or a revoke whose reason is refund or chargeback, revokes keys sent as license files, which keep working offline.

Data

Common fields: product, email, and:

Notes

• For repeat-refund and duplicate, a key not yet bound to a major version counts as any. The key was created as usual, and license.issued was sent first. One per kind.
• One flag per purchase: while it still names a file, a key of it refunded again, or another key of the sale refunded later, adds its ids, and the flag is sent again under the same id, its fileIds every id it names now.
• A flag whose keys were all put back is gone, so a later refund usually sends a new flag with a new id.

A license.flagged event's data:

{  "id": "flg_4f1c9a0e2b7d4c6f8a1b3e5d7c9f0a2b",  "key": "SLUICE-7K2M-Q9XD-4HTR-WB6N",  "product": "sluice",  "kind": "repeat-refund",  "earlierKeys": ["SLUICE-3HVW-7RNC-LD2B-M6PQ"],  "sale": null,  "email": "[email protected]",  "flaggedAt": 1791504000000}

license.expiring

Sent when

A subscription key that is not canceled, or a timed key, has 14 days or fewer before it expires.

Data

Common fields: key, product, email, days, and:

Notes

• Sent once per key for each expiry date.

license.picked_up

Sent when

An app restored a customer's keys by key pickup: the customer typed the code KeyGrant emailed to the address they bought with, and KeyGrant handed that address's keys of the product to the app.

Data

Common fields: key, product, and:

Notes

• One event for each key handed out.
• The app then activates one of them as usual, which sends device.activated.

trial.ending

Sent when

A trial key has 3 days or fewer before it expires.

Data

Common fields: key, product, email, days, and:

Notes

• Sent once per key for each expiry date.
• Not sent for device trials, which have no key.

Device events

device.activated

Sent when

A device took a seat on a key.

Data

Common fields: key, product, and:

Notes

• Not sent again when a device that already holds a seat activates again.

device.released

Sent when

In any of these cases:

• By the app, in the dashboard or over the API.
• By your customer in the customer portal.
• By KeyGrant, for a device that went past its license's days without checking in (see Free unused seats).

Data

Common fields: key, product, and:

Notes

• The events for seats KeyGrant freed go out within minutes of the nightly pass that frees the seats.

A device.released event's data when KeyGrant freed the seat:

{  "key": "SLUICE-7K2M-Q9XD-4HTR-WB6N",  "product": "sluice",  "activationId": "act_3f9c2a71d04b4e8a9c6d1e2f",  "fingerprint": "5e1f0ca7d00d4a37b9c2",  "reason": "inactive",  "lastSeen": 1788912000000}

device.limit_reached

Sent when

A device's activation was refused because every seat was taken.

Data

Common fields: key, product, and:

device.rekeyed

Sent when

A seat activated under its device's host name moved to the device's machine ID.

Data

Common fields: key, product, and:

Notes

• Sent once per seat.

device.shared

Sent when

A seat was seen on two or more machines within 30 days (see Device management).

Data

Common fields: key, product, and:

Notes

• Sent at once the first time, then at most once an hour per seat when the count has grown.

Meter events

For a key whose license model counts uses (see Metered uses). They are sent in the background and never fail a spend or a check-in.

meter.used_up

Sent when

A spend, a report of what a device spent offline, or a spend from your backend took its last use.

Data

Common fields: key, product, email, and:

Notes

• Sent once each time a meter goes from having uses to having none, so a top-up, an add, a reset or an edit that gives it uses again lets it be sent again.
• This is the moment to offer a top-up. KeyGrant sends the customer no such nudge.

meter.overage

Sent when

Its report of spends took a meter past what the key holds. The device spent from its offline allowance while KeyGrant could not be reached, and was never refused for it.

Data

Common fields: key, product, email, and:

Notes

• Sent once for each report that grew the overage, which is at most one a check-in.

Sale events

sale.held

Sent when

A paid upgrade sale, or a timed model's purchase, changed no key: KeyGrant held it, and it waits for you to attach it to a key or refund it. Each kind's causes are linked from Held sales.

Data

Common fields: product, and:

Notes

• No key exists for it, so it carries none.

What sends no event

• An ordinary subscription renewal.
• A failed renewal.
• An extension.
• A change of versions made by hand or over the API.
• A change of entitlements made by hand or over the API.
• A change of meters made by hand or over the API.
• A device trial.