Webhook Event Logs

Overview

This API has been available since 1.53.0

The Webhook Event Log contains a record of Events sent by FusionAuth, including request payloads. It also records attempts to send the event payload to Webhook and Kafka endpoints.

Test events sent through the FusionAuth admin UI are not recorded in the Webhook Event Log.

This page contains the APIs that are used to retrieve Webhook Event Logs and associated attempt details. Here are the APIs:

Retrieve a Webhook Event Log

Request

Retrieve a Webhook Event Log by Id

GET /api/system/webhook-event-log/{logId}

Request Parameters

logIdUUIDrequired

The unique Id of the Webhook Event Log to retrieve.

Response

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you requested doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body

webhookEventLog.attemptsArray

An array of attempts for this event.

webhookEventLog.attempts[x].dataObject

An object that can hold additional details of a webhook attempt log.

webhookEventLog.attempts[x].endInstantLong

The instant the attempt received a response or timed out.

webhookEventLog.attempts[x].idUUID

The unique Id of this webhook attempt.

webhookEventLog.attempts[x].startInstantLong

The instant the attempt request was sent.

webhookEventLog.attempts[x].webhookCallResponse.exceptionString

The exception field from the event receiver if it was present on the response.

webhookEventLog.attempts[x].webhookCallResponse.statusCodeInteger

The HTTP status code from the event response.

webhookEventLog.attempts[x].webhookCallResponse.urlString

The fully qualified URL that was used to send the event to the webhook receiver.

This field will be omitted from the response if this attempt was sent to a Kafka topic.

webhookEventLog.attempts[x].webhookIdUUID

The unique Id of the configured webhook.

This field will be omitted from the response if this attempt was sent to a Kafka topic.

webhookEventLog.dataObject

An object that can hold additional details of a webhook event log.

webhookEventLog.eventObject

Contains the full event request payload. The contents vary by event type.

webhookEventLog.eventResultString

The overall result of a transactional event. Possible values are:

Running - The default state after an event is fired.
Succeeded - The transactional event was successful, and pending database changes were committed. Non-transactional events are transitioned to this state immediately after the event payload is sent to all recipients regardless of the response.
Failed - The transactional event was unsuccessful, and pending database changes were rolled back.

webhookEventLog.eventTypeString

The event type. Possible values are:

audit-log.create - When an audit log is created Available since 1.30.0
event-log.create - When an event log is created Available since 1.30.0
jwt.public-key.update - When a JWT RSA Public / Private keypair may have been changed
jwt.refresh - When an access token is refreshed using a refresh token Available since 1.16.0
jwt.refresh-token.revoke - When a JWT Refresh Token is revoked
kickstart.success - When kickstart has successfully completed Available since 1.30.0
user.action - When a user action is triggered
user.bulk.create - When multiple users are created in bulk (i.e. during an import)
user.create - When a user is created
user.create.complete - When a user create transaction has completed Available since 1.30.0
user.deactivate - When a user is deactivated
user.delete - When a user is deleted
user.delete.complete - When a user delete transaction has completed Available since 1.30.0
user.email.update - When a user updates their email address Available since 1.30.0
user.email.verified - When a user verifies their email address Available since 1.8.0
user.identity-provider.link - When a link is created from a user to an Identity Provider Available since 1.36.0
user.identity-provider.unlink - When an existing Identity Provider link is removed from a User Available since 1.36.0
user.loginId.duplicate.create - When a request to create a user with a login Id (email or username) which is already in use has been received Available since 1.30.0
Note: An Enterprise plan is required to utilize the user.loginId.duplicate.create event .
user.loginId.duplicate.update - When a request to update a user and change their login Id (email or username) to one that is already in use has been received Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.loginId.duplicate.update event .
user.login.failed - When a user fails a login request Available since 1.6.0
user.login.new-device - When a user begins a login request with a new device Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.login.new-device event .
user.login.success - When a user completes a login request Available since 1.6.0
user.login.suspicious - When a user logs in and is considered to be a potential threat (requires an activated Enterprise license) Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.login.suspicious event .
user.password.breach - When Reactor detects a user is using a potentially breached password (requires an activated license) Available since 1.15.0

Note: A paid plan is required to utilize the user.password.breach event .
user.password.reset.send - When a forgot password email has been sent to a user Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.password.reset.send event.
user.password.reset.start - When the process to reset a user password has started Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.password.reset.start event.
user.password.reset.success - When a user has successfully reset their password Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.password.reset.success event.
user.password.update - When a user has updated their password Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.password.update event.
user.reactivate - When a user is reactivated
user.registration.create - When a user registration is created Available since 1.6.0
user.registration.create.complete - When a user registration create transaction has completed Available since 1.30.0
user.registration.delete - When a user registration is deleted Available since 1.6.0
user.registration.delete.complete - When a user registration delete transaction has completed Available since 1.30.0
user.registration.update - When a user registration is updated Available since 1.6.0
user.registration.update.complete - When a user registration update transaction has completed Available since 1.30.0
user.registration.verified - When a user completes registration verification Available since 1.8.0
user.two-factor.method.add - When a user has added a two-factor method Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.two-factor.method.add event.
user.two-factor.method.remove - When a user has removed a two-factor method Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.two-factor.method.remove event.
user.update - When a user is updated
user.update.complete - When a user update transaction has completed Available since 1.30.0

webhookEventLog.failedAttemptsInteger

The number of failed event send attempts. Aggregate based on failed attempts .

webhookEventLog.idUUID

The webhook event log unique Id.

webhookEventLog.insertInstantLong

The instant when the Webhook Event Log was created.

webhookEventLog.lastAttemptInstantLong

The instant the last attempt was made to send the event.

webhookEventLog.lastUpdateInstantLong

The instant when the Webhook Event Log was lasted updated.

webhookEventLog.linkedObjectIdUUID

If present, contains the unique Id of the associated object. The object type the Id references varies based on webhookEventLog.eventType

webhookEventLog.sequenceLong

An auto-incremented database field to maintain order of events.

webhookEventLog.successfulAttemptsInteger

The number of successful event send attempts. Aggregate based on successful attempts .

Example JSON Response

{
  "webhookEventLog": {
    "attempts": [
      {
        "attemptResult": "Success",
        "data": {},
        "endInstant": 1723209475960,
        "id": "00000000-0000-000b-0000-000000000000",
        "startInstant": 1723209475935,
        "webhookCallResponse": {
          "statusCode": 200,
          "url": "http://mygameserver.local:7001/fusionauth-webhook"
        },
        "webhookId": "00d1c9ed-120d-4a71-8b78-50e609d93814"
      }
    ],
    "data": {},
    "event": {
      "event": {
        "type": "jwt.refresh"
      }
    },
    "eventResult": "Running",
    "eventType": "jwt.refresh",
    "failedAttempts": 0,
    "id": "00000000-0000-000a-0000-000000000000",
    "insertInstant": 1723209475930,
    "lastAttemptInstant": 1723209475930,
    "lastUpdateInstant": 1723209475930,
    "linkedObjectId": "00000000-0000-000a-0000-000000000000",
    "sequence": 1,
    "successfulAttempts": 1
  }
}

Retrieve a Webhook Attempt Log

Request

Retrieve a Webhook Attempt Log by Id

GET /api/system/webhook-attempt-log/{logId}

Request Parameters

logIdUUIDrequired

The unique Id of the Webhook Attempt Log to retrieve.

Response

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you requested doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body

webhookAttemptLog.dataObject

An object that can hold additional details of a webhook attempt log.

webhookAttemptLog.endInstantLong

The instant the attempt received a response or timed out.

webhookAttemptLog.idUUID

The unique Id of this webhook attempt.

webhookAttemptLog.startInstantLong

The instant the attempt request was sent.

webhookAttemptLog.webhookCallResponse.exceptionString

The exception field from the event receiver if it was present on the response.

webhookAttemptLog.webhookCallResponse.statusCodeInteger

The HTTP status code from the event response.

webhookAttemptLog.webhookCallResponse.urlString

The fully qualified URL that was used to send the event to the webhook receiver.

This field will be omitted from the response if this attempt was sent to a Kafka topic.

webhookAttemptLog.webhookEventLogIdUUID

The unique Id for the associated webhook event log.

webhookAttemptLog.webhookIdUUID

The unique Id of the configured webhook.

This field will be omitted from the response if this attempt was sent to a Kafka topic.

Example JSON Response

{
  "attemptResult": "Success",
  "data": {},
  "endInstant": 1723209475960,
  "id": "00000000-0000-000b-0000-000000000000",
  "startInstant": 1723209475935,
  "webhookCallResponse": {
    "statusCode": 200,
    "url": "http://mygameserver.local:7001/fusionauth-webhook"
  },
  "webhookEventLogId": "00000000-0000-000a-0000-000000000000",
  "webhookId": "00d1c9ed-120d-4a71-8b78-50e609d93814"
}

Search Webhook Event Logs

Request

Searches the Webhook Event Logs using the given search criteria

GET /api/system/webhook-event-log/search?event={event}&start={start}&end={end}&eventType={eventType}

When calling the API using a GET request you will send the search criteria on the URL using request parameters. In order to simplify the example URL above, not every possible parameter is shown, however using the provided pattern you may add any of the documented request parameters to the URL.

Request Parameters

endLong

The end instant of the date/time range to search within.

eventString

The string to search in the Webhook Event Log request body for. This can contain wildcards using the asterisk character (*). If no wildcards are present, this parameter value will be interpreted as *value*.

eventResultString

The overall result of a transactional event. Possible values are:

Running - The default state after an event is fired.
Succeeded - The transactional event was successful, and pending database changes were committed. Non-transactional events are transitioned to this state immediately after the event payload is sent to all recipients regardless of the response.
Failed - The transactional event was unsuccessful, and pending database changes were rolled back.

eventTypeString

The event type.

numberOfResultsIntegerDefaults to 25

The number of results to return from the search.

orderByStringDefaults to sequence DESC

The database column to order the search results on plus the order direction.

The possible values are:

eventResult - the overall result of the event
eventType - the event type
id - the unique Id of the Webhook Event Log
insertInstant - the instant when the Webhook Event Log was created
lastAttemptInstant - the instant when the last attempt was made to deliver the event
linkedObjectId - the unique Id of the object associated with this event
sequence - the system-assigned event sequence

For example, to order the results by the insert instant in a descending order, the value would be provided as insertInstant DESC. The final string is optional can be set to ASC or DESC.

startLong

The start instant of the date/time range to search within.

startRowIntegerDefaults to 0

The offset row to return results from. If the search has 200 records in it and this is 50, it starts with row 50.

Searches the Webhook Event Logs using the given search criteria

POST /api/system/webhook-event-log/search

When calling the API using a POST request you will send the search criteria in a JSON request body.

Request Body

search.endLong

The end instant of the date/time range to search within.

search.eventString

search.eventResultString

The overall result of a transactional event. Possible values are:

Running - The default state after an event is fired.
Succeeded - The transactional event was successful, and pending database changes were committed. Non-transactional events are transitioned to this state immediately after the event payload is sent to all recipients regardless of the response.
Failed - The transactional event was unsuccessful, and pending database changes were rolled back.

search.eventTypeString

The event type.

search.numberOfResultsIntegerDefaults to 25

The number of results to return from the search.

search.orderByStringDefaults to sequence DESC

The database column to order the search results on plus the order direction.

The possible values are:

eventResult - the overall result of the event
eventType - the event type
id - the unique Id of the Webhook Event Log
insertInstant - the instant when the Webhook Event Log was created
lastAttemptInstant - the instant when the last attempt was made to deliver the event
linkedObjectId - the unique Id of the object associated with this event
sequence - the system-assigned event sequence

For example, to order the results by the insert instant in a descending order, the value would be provided as insertInstant DESC. The final string is optional can be set to ASC or DESC.

search.startLong

The start instant of the date/time range to search within.

search.startRowIntegerDefaults to 0

The offset row to return results from. If the search has 200 records in it and this is 50, it starts with row 50.

Example JSON Request

{
  "search": {
    "eventResult": "Succeeded",
    "eventType": "jwt.refresh",
    "numberOfResults": 25,
    "orderBy": "insertInstant",
    "startRow": 0
  }
}

Response

The response for this API contains the Webhook Event Logs matching the search criteria in paginated format.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you requested doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body

webhookEventLogs[x].attemptsArray

An array of attempts for this event.

webhookEventLogs[x].attempts[x].dataObject

An object that can hold additional details of a webhook attempt log.

webhookEventLogs[x].attempts[x].endInstantLong

The instant the attempt received a response or timed out.

webhookEventLogs[x].attempts[x].idUUID

The unique Id of this webhook attempt.

webhookEventLogs[x].attempts[x].startInstantLong

The instant the attempt request was sent.

webhookEventLogs[x].attempts[x].webhookCallResponse.exceptionString

The exception field from the event receiver if it was present on the response.

webhookEventLogs[x].attempts[x].webhookCallResponse.statusCodeInteger

The HTTP status code from the event response.

webhookEventLogs[x].attempts[x].webhookCallResponse.urlString

The fully qualified URL that was used to send the event to the webhook receiver.

This field will be omitted from the response if this attempt was sent to a Kafka topic.

webhookEventLogs[x].attempts[x].webhookIdUUID

The unique Id of the configured webhook.

This field will be omitted from the response if this attempt was sent to a Kafka topic.

webhookEventLogs[x].dataObject

An object that can hold additional details of a webhook event log.

webhookEventLogs[x].eventObject

Contains the full event request payload. The contents vary by event type.

webhookEventLogs[x].eventResultString

The overall result of a transactional event. Possible values are:

Running - The default state after an event is fired.
Succeeded - The transactional event was successful, and pending database changes were committed. Non-transactional events are transitioned to this state immediately after the event payload is sent to all recipients regardless of the response.
Failed - The transactional event was unsuccessful, and pending database changes were rolled back.

webhookEventLogs[x].eventTypeString

The event type. Possible values are:

audit-log.create - When an audit log is created Available since 1.30.0
event-log.create - When an event log is created Available since 1.30.0
jwt.public-key.update - When a JWT RSA Public / Private keypair may have been changed
jwt.refresh - When an access token is refreshed using a refresh token Available since 1.16.0
jwt.refresh-token.revoke - When a JWT Refresh Token is revoked
kickstart.success - When kickstart has successfully completed Available since 1.30.0
user.action - When a user action is triggered
user.bulk.create - When multiple users are created in bulk (i.e. during an import)
user.create - When a user is created
user.create.complete - When a user create transaction has completed Available since 1.30.0
user.deactivate - When a user is deactivated
user.delete - When a user is deleted
user.delete.complete - When a user delete transaction has completed Available since 1.30.0
user.email.update - When a user updates their email address Available since 1.30.0
user.email.verified - When a user verifies their email address Available since 1.8.0
user.identity-provider.link - When a link is created from a user to an Identity Provider Available since 1.36.0
user.identity-provider.unlink - When an existing Identity Provider link is removed from a User Available since 1.36.0
user.loginId.duplicate.create - When a request to create a user with a login Id (email or username) which is already in use has been received Available since 1.30.0
Note: An Enterprise plan is required to utilize the user.loginId.duplicate.create event .
user.loginId.duplicate.update - When a request to update a user and change their login Id (email or username) to one that is already in use has been received Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.loginId.duplicate.update event .
user.login.failed - When a user fails a login request Available since 1.6.0
user.login.new-device - When a user begins a login request with a new device Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.login.new-device event .
user.login.success - When a user completes a login request Available since 1.6.0
user.login.suspicious - When a user logs in and is considered to be a potential threat (requires an activated Enterprise license) Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.login.suspicious event .
user.password.breach - When Reactor detects a user is using a potentially breached password (requires an activated license) Available since 1.15.0

Note: A paid plan is required to utilize the user.password.breach event .
user.password.reset.send - When a forgot password email has been sent to a user Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.password.reset.send event.
user.password.reset.start - When the process to reset a user password has started Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.password.reset.start event.
user.password.reset.success - When a user has successfully reset their password Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.password.reset.success event.
user.password.update - When a user has updated their password Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.password.update event.
user.reactivate - When a user is reactivated
user.registration.create - When a user registration is created Available since 1.6.0
user.registration.create.complete - When a user registration create transaction has completed Available since 1.30.0
user.registration.delete - When a user registration is deleted Available since 1.6.0
user.registration.delete.complete - When a user registration delete transaction has completed Available since 1.30.0
user.registration.update - When a user registration is updated Available since 1.6.0
user.registration.update.complete - When a user registration update transaction has completed Available since 1.30.0
user.registration.verified - When a user completes registration verification Available since 1.8.0
user.two-factor.method.add - When a user has added a two-factor method Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.two-factor.method.add event.
user.two-factor.method.remove - When a user has removed a two-factor method Available since 1.30.0

Note: An Enterprise plan is required to utilize the user.two-factor.method.remove event.
user.update - When a user is updated
user.update.complete - When a user update transaction has completed Available since 1.30.0

webhookEventLogs[x].failedAttemptsInteger

The number of failed event send attempts. Aggregate based on failed attempts .

webhookEventLogs[x].idUUID

The webhook event log unique Id.

webhookEventLogs[x].insertInstantLong

The instant when the Webhook Event Log was created.

webhookEventLogs[x].lastAttemptInstantLong

The instant the last attempt was made to send the event.

webhookEventLogs[x].lastUpdateInstantLong

The instant when the Webhook Event Log was lasted updated.

webhookEventLogs[x].linkedObjectIdUUID

If present, contains the unique Id of the associated object. The object type the Id references varies based on webhookEventLogs[x].eventType

webhookEventLogs[x].sequenceLong

An auto-incremented database field to maintain order of events.

webhookEventLogs[x].successfulAttemptsInteger

The number of successful event send attempts. Aggregate based on successful attempts .

totalInteger

The total number of Webhook Event Logs matching the search criteria. Use this value along with the numberOfResults and startRow in the Search request to perform pagination.

Example JSON Response

{
  "total": 1,
  "webhookEventLogs": [
    {
      "attempts": [
        {
          "attemptResult": "Success",
          "data": {},
          "endInstant": 1723209475960,
          "id": "00000000-0000-000b-0000-000000000000",
          "startInstant": 1723209475935,
          "webhookCallResponse": {
            "statusCode": 200,
            "url": "http://mygameserver.local:7001/fusionauth-webhook"
          },
          "webhookId": "00d1c9ed-120d-4a71-8b78-50e609d93814"
        }
      ],
      "data": {},
      "event": {
        "event": {
          "type": "jwt.refresh"
        }
      },
      "eventResult": "Running",
      "eventType": "jwt.refresh",
      "failedAttempts": 0,
      "id": "00000000-0000-000a-0000-000000000000",
      "insertInstant": 1723209475930,
      "lastAttemptInstant": 1723209475930,
      "lastUpdateInstant": 1723209475930,
      "linkedObjectId": "00000000-0000-000a-0000-000000000000",
      "sequence": 1,
      "successfulAttempts": 1
    }
  ]
}

Results

Recent

Webhook Event Logs

Overview

Retrieve a Webhook Event Log

Request

Request Parameters

Response

Response Body

Retrieve a Webhook Attempt Log

Request

Request Parameters

Response

Response Body

Search Webhook Event Logs

Request

Request Parameters

Request Body

Response

Response Body

Results

Recent