Webhooks
Get notified when a license is created, revoked, changes plan or seats, or a trial ends. Every event and payload, HMAC signature checks and retries.
Webhooks tell your other systems when something happens to a license. A CRM can tag a customer when they buy, a SaaS backend can lock an account when a license is revoked or grant access when a team grows, and a chat channel can announce every new sale. Keygate sends an HTTPS POST to your endpoint for each event you subscribe to.
Add an endpoint
Open Webhooks in the dashboard, pick the product, enter the URL that should receive events and choose the events you want. Every event in the list below can be chosen there. Keygate generates a signing secret for the endpoint; store it on your side, you need it to check that a request really came from Keygate.
An endpoint belongs to one product and receives that product's events only. To hear about several products, add an endpoint for each; they can share a URL.
Use the test button to send a webhook.test event and see it arrive, whatever the endpoint subscribes to. Every delivery is listed with its response code, and any of them can be sent again from there.
Through the admin API, POST /admin/webhooks takes product_id, url and events and needs a key with the admin scope. Event names are checked against the list below, and anything else answers 400.
What a delivery looks like
The body is JSON with the event name, a timestamp in UTC and the data for that event:
{
"event": "license.created",
"timestamp": "2026-10-04T09:12:44Z",
"data": {
"license_id": "4f0c6c1e-2a7b-4d4e-9a55-0d3b7e1f2c11",
"email": "[email protected]",
"plan_id": "9b2d7e40-5c1a-4f8e-b3d6-1a7c0e9f4b25"
}
}Three headers come with it:
| Header | Contains |
|---|---|
X-Keygate-Event | The event name, the same as in the body. |
X-Keygate-Signature | sha256= followed by the HMAC of the body, in hex. |
X-Keygate-Delivery | A unique ID for this delivery. |
Verify the signature
Compute an HMAC SHA256 of the raw request body with your endpoint's secret and compare it with the header. Use the body exactly as it arrived; parsing and serializing the JSON again changes the bytes and the signature no longer matches.
import { createHmac, timingSafeEqual } from "node:crypto";
export function isFromKeygate(rawBody, signatureHeader, secret) {
const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signatureHeader ?? "");
return a.length === b.length && timingSafeEqual(a, b);
}func isFromKeygate(body []byte, signatureHeader, secret string) bool {
mac := hmac.New(sha256.New, []byte(secret))
mac.Write(body)
expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(expected), []byte(signatureHeader))
}Answer with any 2xx status once you have accepted the event. Do slow work after you reply, because Keygate waits ten seconds by default, set by WEBHOOK_HTTP_TIMEOUT, before it treats the delivery as failed.
Events
License events carry license_id in their data, plus the fields listed here. A null date means there is no limit.
| Event | Sent when | Data |
|---|---|---|
license.created | A license is created by a checkout, in the dashboard, through the API or by a self sign up. | email, plan_id. A self sign up adds signup_source (self_signup) and marketing_consent. |
license.activated | A new device or user is activated on a license. Activating one it already knows sends nothing. | identifier, type |
license.deactivated | A device is removed from a license: by your app, in the customer portal or in the dashboard. Also sent for each device that goes with a removed team member, and for each device removed when a license key or a member's key is reissued. | identifier |
license.expiry_changed | An admin changes a license's end date. | email, valid_until |
license.updates_changed | The end of a license's update period moves. reason is admin when an admin set it, renewal when a paid renewal extended it and renewal_refunded when a renewal was refunded in full and its time taken back. | email, updates_until, reason |
license.expired | A license stops working on its own. reason is grace_period_ended after the end date and grace days, trial_ended when a trial runs out and does not move to a fallback plan (see when a trial ends), or past_due_timeout when a subscription has been past due for 30 days. An upgraded license goes back to its free plan instead and sends plan.changed. | email, reason |
license.canceled | The subscription behind a license ends: subscription_deleted when Stripe deletes it, or subscription_unpaid, sent once, when it turns unpaid. Stripe never deletes an unpaid subscription, so that is the only event for it. | email, reason |
license.suspended | An admin suspends a license, or its subscription is paused in Stripe (reason subscription_paused). | email, reason for a pause |
license.reinstated | A suspended license is reinstated by an admin or resumed in Stripe, an admin gives an expired license a new end date, or a payment brings back a license that ended unpaid or expired for non-payment. | email, status when an admin did it |
license.revoked | An admin revokes a license, uses Cancel and revoke, or a purchase is refunded in full in Stripe (both with reason refund), or a dispute over it is lost (reason dispute_lost). A refunded upgrade, or one whose dispute is lost, sends plan.changed instead, and a refunded renewal license.updates_changed. | email, reason on Cancel and revoke and on a refund |
license.payment_failed | A subscription payment fails. | email |
license.payment_recovered | A failed payment goes through after all. | email |
license.quantity_changed | The number of seats a license is paid for changes on a plan sold per seat. See license.quantity_changed below. | email, plan_id, old_quantity, new_quantity, reason for an upgrade |
plan.changed | A license moves to another plan: an admin changes it, the customer switches plans in the portal or you change the price in Stripe, a paid upgrade is applied, an upgrade is undone and the license goes back to its free plan, or a trial moves to its fallback plan. Only the last two carry a reason, listed below. | old_plan_id, new_plan_id, reason when undone or at the end of a trial, email at the end of a trial, old_quantity and new_quantity when an admin moves the license to a plan sold per seat and its seats change |
seat.added | A team member is invited to a license (outcome created), or someone who was removed is invited again (restored). Inviting again someone who has not joined yet sends a new invitation email but no event, and inviting someone already on the team does nothing. It is sent at the invitation: accepting it, or being paused because the team is over its seats, sends no event. | seat_id, email, role (always member), outcome |
seat.removed | The license owner removes a member or cancels an invitation in the portal, or an admin does it in the dashboard. Sent once. The member's own key stops working, and each of their devices follows as a license.deactivated. | seat_id, email |
quota.warning | A usage call takes a quota across its warning level. Sent once per crossing. | feature, used, limit, threshold |
quota.exceeded | A usage call is refused because the quota is spent. Sent for every refused call, not once; a call that lands exactly on the limit is accepted and sends nothing. | feature, used, limit |
release.published | A release is published. | release_id, version, channel, platforms |
release.yanked | A release is pulled. | The same as release.published. |
release.unyanked | A pulled release is put back. | The same as release.published. |
Why plan.changed carries a reason
A license that was upgraded from a free plan keeps its key on the paid plan. When the payment no longer stands, it goes back to the free plan and plan.changed carries one of the first six reasons below. The last one is sent when a trial moves to its fallback plan.
| Reason | What happened |
|---|---|
refund | The upgrade's payment was refunded in full in Stripe. |
subscription_ended | The upgrade's subscription was canceled. |
subscription_unpaid | The subscription turned unpaid. |
past_due_timeout | The subscription was past due for 30 days. |
grace_period_ended | The subscription's period and the plan's grace days ran out without a renewal. |
admin_canceled | An admin used Cancel and revoke on the license. |
trial_ended | The license's trial ran out and its trial plan names a fallback plan, so it moved there instead of expiring. See when a trial ends. |
license.quantity_changed
This event tells you that the number of seats a license is paid for has changed, on a plan sold per seat or moving to or from one. On such a plan the seats set how many people the license holds, and its devices are the plan's devices per seat times the seats, so a SaaS backend can use this event to grow or shrink a team's access. It is sent when:
- the customer changes the seats in the customer portal, or you change the subscription's quantity in Stripe, once Stripe has applied the change. A change still waiting for payment sends nothing until it is paid;
- an admin sets the seats of a per-seat license that nothing bills;
- upgrading a free license to a plan sold per seat changes its seats, or undoing that upgrade puts them back.
reasonis thenupgradeorupgrade_reverted.
{
"event": "license.quantity_changed",
"timestamp": "2026-10-26T14:03:18Z",
"data": {
"license_id": "4f0c6c1e-2a7b-4d4e-9a55-0d3b7e1f2c11",
"email": "[email protected]",
"plan_id": "9b2d7e40-5c1a-4f8e-b3d6-1a7c0e9f4b25",
"old_quantity": 5,
"new_quantity": 8
}
}- A change of plan and seats together through Stripe or the portal sends both
plan.changedandlicense.quantity_changed. The dashboard's Change Plan sends onlyplan.changed, carryingold_quantityandnew_quantity. - A downgrade in the portal is sent once Stripe confirms it, or at once when Stripe's answer is lost. If it then turns out that Stripe did not make the change, a second event moves the seats, and the plan, back.
- See changing plans and seats for how customers change their seats and how it is billed.
When a trial ends
This section covers which event a trial sends when it runs out. A trial plan can name a fallback plan, a free plan of the same product. When it does, the license moves there instead of expiring: it keeps its key and devices, the fallback plan's limits apply, and plan.changed is sent with reason trial_ended and the license's email:
{
"event": "plan.changed",
"timestamp": "2026-10-26T15:00:02Z",
"data": {
"license_id": "4f0c6c1e-2a7b-4d4e-9a55-0d3b7e1f2c11",
"email": "[email protected]",
"old_plan_id": "1d6a3f2e-8c4b-4e1a-9f7d-2b5c8e0a6d13",
"new_plan_id": "7e9b1c4d-3a2f-4b8e-a6d5-0c1f9e2b7a48",
"reason": "trial_ended"
}
}The trial expires instead, and sends license.expired with reason trial_ended, when:
- The trial plan names no fallback plan.
- A Stripe subscription bills the trial. Stripe settles those, and Keygate expires one only if nothing is heard from Stripe past the plan's grace days, at least one day. See trials billed by Stripe.
- The fallback plan no longer qualifies when the trial ends. The dashboard refuses edits that would cause this.
Both happen in an hourly check, so the event arrives within about an hour of the trial's end date, or later for a trial Stripe bills.
Retries and duplicates
If your endpoint does not answer with 2xx, Keygate tries again after one minute, then after two, four and eight minutes. It gives up after five attempts in all, a number you can change with WEBHOOK_MAX_ATTEMPTS.
- Automatic retries keep the same
X-Keygate-DeliveryID, so you can skip an ID you have already processed. - A delivery sent again by hand from the dashboard gets a new ID but carries exactly the same body. If an event must never be processed twice, remember the event name, the timestamp and the license ID together.
Private addresses
To protect your network, Keygate refuses to deliver to private, loopback and link local addresses by default, including numeric shorthands for them such as 2130706433 or 127.1, which are refused when the endpoint is saved. If your receiver runs on the same machine or Docker network, set WEBHOOK_ALLOW_PRIVATE=true.
Frequently asked questions
Which webhook tells me that a customer bought more or fewer seats?
license.quantity_changed. It carries old_quantity and new_quantity and is sent once the change has been applied: after Stripe made it, whether the customer changed the seats in the portal or you changed the quantity in Stripe, or when an admin set the seats of a license nothing bills. A change still waiting for payment sends nothing yet.
Which webhook is sent when a trial ends?
If the trial plan names a fallback plan, the license moves there and plan.changed is sent with reason trial_ended and the license's email. Otherwise, or when Stripe bills the trial, or the fallback plan no longer qualifies, the license expires and license.expired is sent with reason trial_ended.
What is sent when a team member is removed?
seat.removed, once, with the seat ID and the member's email. The member's own license key stops working, and each device they had activated is removed and reported as its own license.deactivated.
Last updated October 26, 2026