Skip to content

docs: document Grant.LimitExceeded webhook event - #1460

Merged
simeng-li merged 3 commits into
masterfrom
simeng-docs-add-grant-limit-exceeded-webhook
Jul 30, 2026
Merged

docs: document Grant.LimitExceeded webhook event#1460
simeng-li merged 3 commits into
masterfrom
simeng-docs-add-grant-limit-exceeded-webhook

Conversation

@simeng-li

Copy link
Copy Markdown
Contributor

Summary

Documents the Grant.LimitExceeded webhook event added in logto-io/logto#9230 (community contribution by @Kathircpe). The event fires when a successful authorization pushes a user past an app's maxAllowedGrants limit and Logto revokes their oldest grants.

What changed

  • docs/developers/webhooks/events.mdx — added Grant.LimitExceeded to the security exception hook events table.
  • docs/developers/webhooks/request.mdx — restructured "Exception event payloads" into per-event subsections, since the family no longer has one shared shape. Grant.LimitExceeded is emitted from the OIDC authorization endpoint rather than the Experience API, so unlike Identifier.Lockout it carries no interactionEvent or sessionId. Added the full field table (userId, applicationId, application, maxAllowedGrants, preRevocationActiveGrantCount, revokedGrantIds), an example payload, and delivery notes.
  • docs/sessions/session-configs.mdx — added "Monitor evictions with a webhook" under max concurrent authenticated devices, plus a related-resources link.
  • docs/integrate-logto/application-data-structure.mdx — one-line pointer from the maxAllowedGrants field reference to the event.

Out of the original scope, but included

Message.RateLimited shipped in the event catalog but was never added to webhooks-request. Splitting the exception section per-event made that omission structural, so it now has its own { action, recipient } subsection and appears in the request-body family table.

Expected result

Readers subscribing to Grant.LimitExceeded in Console can find the exact payload shape without reading the core source. The field names and optionality below were verified against packages/core/src/event-listeners/authorization-success.ts and packages/core/src/libraries/hook/index.ts at the merge commit:

  • revokedGrantIds lists only grants that were actually revoked, oldest first (pMap preserves input order over the iat-sorted list).
  • application is optional — the lookup is wrapped in trySafe and omitted on failure.
  • Dispatch is fire-and-forget, so a failing endpoint never blocks the authorization.

Testing

N/A

Checklist

  • .changeset
  • unit tests
  • integration tests
  • necessary TSDoc comments

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Jul 28, 2026

Copy link
Copy Markdown

Deploying logto-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: 504ade8
Status: ✅  Deploy successful!
Preview URL: https://c0b3bfd7.logto-docs.pages.dev
Branch Preview URL: https://simeng-docs-add-grant-limit.logto-docs.pages.dev

View logs

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Jul 28, 2026

Copy link
Copy Markdown

Deploying logto-docs-tutorials with  Cloudflare Pages  Cloudflare Pages

Latest commit: 504ade8
Status: ✅  Deploy successful!
Preview URL: https://eb155360.logto-docs-tutorials.pages.dev
Branch Preview URL: https://simeng-docs-add-grant-limit.logto-docs-tutorials.pages.dev

View logs

@charIeszhao charIeszhao left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See inline comment.

Comment thread docs/developers/webhooks/request.mdx Outdated
@simeng-li
simeng-li enabled auto-merge (squash) July 30, 2026 08:33
@simeng-li
simeng-li merged commit ecfdfeb into master Jul 30, 2026
19 checks passed
@simeng-li
simeng-li deleted the simeng-docs-add-grant-limit-exceeded-webhook branch July 30, 2026 11:48

**Common use cases:**

- Notify the user that they were signed out on another device, and from where.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The webhook does not include the revoked device IP or location, and the revoked grant row is destroyed, so and from where is not implementable. Could we remove , and from where from this bullet?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants