Logto Hooks API
Hook enables you to effortlessly receive real-time updates regarding specific events, such as user registration, sign-in, or password reset. See [🪝 Webhooks] to get started and learn more.
OpenAPI Specification
openapi: 3.0.1
info:
title: Logto API references Account center Hooks API
description: 'API references for Logto services.
Note: The documentation is for Logto Cloud. If you are using Logto OSS, please refer to the response of `/api/swagger.json` endpoint on your Logto instance.'
version: Cloud
servers:
- url: https://[tenant_id].logto.app/
description: Logto endpoint address.
security:
- OAuth2:
- all
tags:
- name: Hooks
description: Hook enables you to effortlessly receive real-time updates regarding specific events, such as user registration, sign-in, or password reset. See [🪝 Webhooks] to get started and learn more.
paths:
/api/hooks:
get:
operationId: ListHooks
tags:
- Hooks
parameters:
- name: includeExecutionStats
in: query
required: false
schema:
type: string
description: Whether to include execution stats in the response.
- name: page
in: query
description: Page number (starts from 1).
required: false
schema:
type: integer
minimum: 1
default: 1
- name: page_size
in: query
description: Entries per page.
required: false
schema:
type: integer
minimum: 1
default: 20
responses:
'200':
description: A list of hooks.
content:
application/json:
schema:
type: array
items:
type: object
required:
- tenantId
- id
- name
- event
- events
- config
- signingKey
- enabled
- createdAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
maxLength: 256
event:
type: string
enum:
- PostRegister
- PostSignIn
- PostSignInAdaptiveMfaTriggered
- PostResetPassword
- User.Created
- User.Deleted
- User.Data.Updated
- User.SuspensionStatus.Updated
- Role.Created
- Role.Deleted
- Role.Data.Updated
- Role.Scopes.Updated
- Scope.Created
- Scope.Deleted
- Scope.Data.Updated
- Organization.Created
- Organization.Deleted
- Organization.Data.Updated
- Organization.Membership.Updated
- OrganizationRole.Created
- OrganizationRole.Deleted
- OrganizationRole.Data.Updated
- OrganizationRole.Scopes.Updated
- OrganizationScope.Created
- OrganizationScope.Deleted
- OrganizationScope.Data.Updated
- Identifier.Lockout
nullable: true
events:
type: array
items:
type: string
enum:
- PostRegister
- PostSignIn
- PostSignInAdaptiveMfaTriggered
- PostResetPassword
- User.Created
- User.Deleted
- User.Data.Updated
- User.SuspensionStatus.Updated
- Role.Created
- Role.Deleted
- Role.Data.Updated
- Role.Scopes.Updated
- Scope.Created
- Scope.Deleted
- Scope.Data.Updated
- Organization.Created
- Organization.Deleted
- Organization.Data.Updated
- Organization.Membership.Updated
- OrganizationRole.Created
- OrganizationRole.Deleted
- OrganizationRole.Data.Updated
- OrganizationRole.Scopes.Updated
- OrganizationScope.Created
- OrganizationScope.Deleted
- OrganizationScope.Data.Updated
- Identifier.Lockout
config:
type: object
required:
- url
properties:
url:
type: string
headers:
type: object
additionalProperties:
type: string
retries:
type: number
signingKey:
type: string
maxLength: 64
enabled:
type: boolean
createdAt:
type: number
executionStats:
type: object
required:
- successCount
- requestCount
properties:
successCount:
type: number
requestCount:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Get hooks
description: Get a list of hooks with optional pagination.
post:
operationId: CreateHook
tags:
- Hooks
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- config
properties:
tenantId:
type: string
maxLength: 21
name:
type: string
minLength: 1
maxLength: 256
description: The name of the hook.
event:
type: string
enum:
- PostRegister
- PostSignIn
- PostSignInAdaptiveMfaTriggered
- PostResetPassword
- User.Created
- User.Deleted
- User.Data.Updated
- User.SuspensionStatus.Updated
- Role.Created
- Role.Deleted
- Role.Data.Updated
- Role.Scopes.Updated
- Scope.Created
- Scope.Deleted
- Scope.Data.Updated
- Organization.Created
- Organization.Deleted
- Organization.Data.Updated
- Organization.Membership.Updated
- OrganizationRole.Created
- OrganizationRole.Deleted
- OrganizationRole.Data.Updated
- OrganizationRole.Scopes.Updated
- OrganizationScope.Created
- OrganizationScope.Deleted
- OrganizationScope.Data.Updated
- Identifier.Lockout
deprecated: true
description: Use `events` instead.
events:
type: array
items:
type: string
enum:
- PostRegister
- PostSignIn
- PostSignInAdaptiveMfaTriggered
- PostResetPassword
- User.Created
- User.Deleted
- User.Data.Updated
- User.SuspensionStatus.Updated
- Role.Created
- Role.Deleted
- Role.Data.Updated
- Role.Scopes.Updated
- Scope.Created
- Scope.Deleted
- Scope.Data.Updated
- Organization.Created
- Organization.Deleted
- Organization.Data.Updated
- Organization.Membership.Updated
- OrganizationRole.Created
- OrganizationRole.Deleted
- OrganizationRole.Data.Updated
- OrganizationRole.Scopes.Updated
- OrganizationScope.Created
- OrganizationScope.Deleted
- OrganizationScope.Data.Updated
- Identifier.Lockout
description: An array of hook events.
config:
type: object
required:
- url
properties:
url:
type: string
headers:
type: object
additionalProperties:
type: string
retries:
type: number
deprecated: true
description: Now the retry times is fixed to 3. Keep for backward compatibility.
enabled:
type: boolean
createdAt:
type: number
responses:
'201':
description: The hook was created successfully.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- name
- event
- events
- config
- signingKey
- enabled
- createdAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
maxLength: 256
event:
type: string
enum:
- PostRegister
- PostSignIn
- PostSignInAdaptiveMfaTriggered
- PostResetPassword
- User.Created
- User.Deleted
- User.Data.Updated
- User.SuspensionStatus.Updated
- Role.Created
- Role.Deleted
- Role.Data.Updated
- Role.Scopes.Updated
- Scope.Created
- Scope.Deleted
- Scope.Data.Updated
- Organization.Created
- Organization.Deleted
- Organization.Data.Updated
- Organization.Membership.Updated
- OrganizationRole.Created
- OrganizationRole.Deleted
- OrganizationRole.Data.Updated
- OrganizationRole.Scopes.Updated
- OrganizationScope.Created
- OrganizationScope.Deleted
- OrganizationScope.Data.Updated
- Identifier.Lockout
nullable: true
events:
type: array
items:
type: string
enum:
- PostRegister
- PostSignIn
- PostSignInAdaptiveMfaTriggered
- PostResetPassword
- User.Created
- User.Deleted
- User.Data.Updated
- User.SuspensionStatus.Updated
- Role.Created
- Role.Deleted
- Role.Data.Updated
- Role.Scopes.Updated
- Scope.Created
- Scope.Deleted
- Scope.Data.Updated
- Organization.Created
- Organization.Deleted
- Organization.Data.Updated
- Organization.Membership.Updated
- OrganizationRole.Created
- OrganizationRole.Deleted
- OrganizationRole.Data.Updated
- OrganizationRole.Scopes.Updated
- OrganizationScope.Created
- OrganizationScope.Deleted
- OrganizationScope.Data.Updated
- Identifier.Lockout
config:
type: object
required:
- url
properties:
url:
type: string
headers:
type: object
additionalProperties:
type: string
retries:
type: number
signingKey:
type: string
maxLength: 64
enabled:
type: boolean
createdAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Create a hook
description: Create a new hook with the given data.
/api/hooks/{id}:
get:
operationId: GetHook
tags:
- Hooks
parameters:
- $ref: '#/components/parameters/hookId-root'
- name: includeExecutionStats
in: query
required: false
schema:
type: string
description: Whether to include execution stats in the response.
responses:
'200':
description: Details of the hook.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- name
- event
- events
- config
- signingKey
- enabled
- createdAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
maxLength: 256
event:
type: string
enum:
- PostRegister
- PostSignIn
- PostSignInAdaptiveMfaTriggered
- PostResetPassword
- User.Created
- User.Deleted
- User.Data.Updated
- User.SuspensionStatus.Updated
- Role.Created
- Role.Deleted
- Role.Data.Updated
- Role.Scopes.Updated
- Scope.Created
- Scope.Deleted
- Scope.Data.Updated
- Organization.Created
- Organization.Deleted
- Organization.Data.Updated
- Organization.Membership.Updated
- OrganizationRole.Created
- OrganizationRole.Deleted
- OrganizationRole.Data.Updated
- OrganizationRole.Scopes.Updated
- OrganizationScope.Created
- OrganizationScope.Deleted
- OrganizationScope.Data.Updated
- Identifier.Lockout
nullable: true
events:
type: array
items:
type: string
enum:
- PostRegister
- PostSignIn
- PostSignInAdaptiveMfaTriggered
- PostResetPassword
- User.Created
- User.Deleted
- User.Data.Updated
- User.SuspensionStatus.Updated
- Role.Created
- Role.Deleted
- Role.Data.Updated
- Role.Scopes.Updated
- Scope.Created
- Scope.Deleted
- Scope.Data.Updated
- Organization.Created
- Organization.Deleted
- Organization.Data.Updated
- Organization.Membership.Updated
- OrganizationRole.Created
- OrganizationRole.Deleted
- OrganizationRole.Data.Updated
- OrganizationRole.Scopes.Updated
- OrganizationScope.Created
- OrganizationScope.Deleted
- OrganizationScope.Data.Updated
- Identifier.Lockout
config:
type: object
required:
- url
properties:
url:
type: string
headers:
type: object
additionalProperties:
type: string
retries:
type: number
signingKey:
type: string
maxLength: 64
enabled:
type: boolean
createdAt:
type: number
executionStats:
type: object
required:
- successCount
- requestCount
properties:
successCount:
type: number
requestCount:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Get hook
description: Get hook details by ID.
patch:
operationId: UpdateHook
tags:
- Hooks
parameters:
- $ref: '#/components/parameters/hookId-root'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
tenantId:
type: string
maxLength: 21
name:
type: string
minLength: 1
maxLength: 256
description: The updated name of the hook.
event:
type: string
enum:
- PostRegister
- PostSignIn
- PostSignInAdaptiveMfaTriggered
- PostResetPassword
- User.Created
- User.Deleted
- User.Data.Updated
- User.SuspensionStatus.Updated
- Role.Created
- Role.Deleted
- Role.Data.Updated
- Role.Scopes.Updated
- Scope.Created
- Scope.Deleted
- Scope.Data.Updated
- Organization.Created
- Organization.Deleted
- Organization.Data.Updated
- Organization.Membership.Updated
- OrganizationRole.Created
- OrganizationRole.Deleted
- OrganizationRole.Data.Updated
- OrganizationRole.Scopes.Updated
- OrganizationScope.Created
- OrganizationScope.Deleted
- OrganizationScope.Data.Updated
- Identifier.Lockout
nullable: true
deprecated: true
description: Use `events` instead.
events:
type: array
items:
type: string
enum:
- PostRegister
- PostSignIn
- PostSignInAdaptiveMfaTriggered
- PostResetPassword
- User.Created
- User.Deleted
- User.Data.Updated
- User.SuspensionStatus.Updated
- Role.Created
- Role.Deleted
- Role.Data.Updated
- Role.Scopes.Updated
- Scope.Created
- Scope.Deleted
- Scope.Data.Updated
- Organization.Created
- Organization.Deleted
- Organization.Data.Updated
- Organization.Membership.Updated
- OrganizationRole.Created
- OrganizationRole.Deleted
- OrganizationRole.Data.Updated
- OrganizationRole.Scopes.Updated
- OrganizationScope.Created
- OrganizationScope.Deleted
- OrganizationScope.Data.Updated
- Identifier.Lockout
description: An array of updated hook events.
config:
type: object
required:
- url
properties:
url:
type: string
headers:
type: object
additionalProperties:
type: string
retries:
type: number
deprecated: true
description: Now the retry times is fixed to 3. Keep for backward compatibility.
enabled:
type: boolean
createdAt:
type: number
responses:
'200':
description: The hook was updated successfully.
content:
application/json:
schema:
type: object
required:
- tenantId
- id
- name
- event
- events
- config
- signingKey
- enabled
- createdAt
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
name:
type: string
maxLength: 256
event:
type: string
enum:
- PostRegister
- PostSignIn
- PostSignInAdaptiveMfaTriggered
- PostResetPassword
- User.Created
- User.Deleted
- User.Data.Updated
- User.SuspensionStatus.Updated
- Role.Created
- Role.Deleted
- Role.Data.Updated
- Role.Scopes.Updated
- Scope.Created
- Scope.Deleted
- Scope.Data.Updated
- Organization.Created
- Organization.Deleted
- Organization.Data.Updated
- Organization.Membership.Updated
- OrganizationRole.Created
- OrganizationRole.Deleted
- OrganizationRole.Data.Updated
- OrganizationRole.Scopes.Updated
- OrganizationScope.Created
- OrganizationScope.Deleted
- OrganizationScope.Data.Updated
- Identifier.Lockout
nullable: true
events:
type: array
items:
type: string
enum:
- PostRegister
- PostSignIn
- PostSignInAdaptiveMfaTriggered
- PostResetPassword
- User.Created
- User.Deleted
- User.Data.Updated
- User.SuspensionStatus.Updated
- Role.Created
- Role.Deleted
- Role.Data.Updated
- Role.Scopes.Updated
- Scope.Created
- Scope.Deleted
- Scope.Data.Updated
- Organization.Created
- Organization.Deleted
- Organization.Data.Updated
- Organization.Membership.Updated
- OrganizationRole.Created
- OrganizationRole.Deleted
- OrganizationRole.Data.Updated
- OrganizationRole.Scopes.Updated
- OrganizationScope.Created
- OrganizationScope.Deleted
- OrganizationScope.Data.Updated
- Identifier.Lockout
config:
type: object
required:
- url
properties:
url:
type: string
headers:
type: object
additionalProperties:
type: string
retries:
type: number
signingKey:
type: string
maxLength: 64
enabled:
type: boolean
createdAt:
type: number
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Update hook
description: Update hook details by ID with the given data.
delete:
operationId: DeleteHook
tags:
- Hooks
parameters:
- $ref: '#/components/parameters/hookId-root'
responses:
'204':
description: The hook was deleted successfully.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Delete hook
description: Delete hook by ID.
/api/hooks/{id}/recent-logs:
get:
operationId: ListHookRecentLogs
tags:
- Hooks
parameters:
- $ref: '#/components/parameters/hookId-root'
- name: logKey
in: query
required: false
schema:
type: string
description: The log key to filter logs.
- name: page
in: query
description: Page number (starts from 1).
required: false
schema:
type: integer
minimum: 1
default: 1
- name: page_size
in: query
description: Entries per page.
required: false
schema:
type: integer
minimum: 1
default: 20
responses:
'200':
description: A list of recent logs for the hook.
content:
application/json:
schema:
type: array
items:
type: object
required:
- id
- key
- payload
- createdAt
properties:
id:
type: string
minLength: 1
maxLength: 21
key:
type: string
minLength: 1
maxLength: 128
payload:
type: object
required:
- key
- result
properties:
key:
type: string
result:
type: string
enum:
- Success
- Error
error:
oneOf:
- type: object
additionalProperties:
example: {}
- type: string
ip:
type: string
userAgent:
type: string
userAgentParsed:
type: object
properties:
ua:
type: string
browser:
type: object
properties:
name:
type: string
version:
type: string
major:
type: string
type:
type: string
device:
type: object
properties:
model:
type: string
type:
type: string
vendor:
type: string
engine:
type: object
properties:
name:
type: string
version:
type: string
os:
type: object
properties:
name:
type: string
version:
type: string
cpu:
type: object
properties:
architecture:
type: string
userId:
type: string
applicationId:
type: string
sessionId:
type: string
params:
type: object
additionalProperties:
example: {}
createdAt:
type: number
'400':
description: Bad Request
'401':
de
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/logto/refs/heads/main/openapi/logto-hooks-api-openapi.yml