Webhook Event Log API

version

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}

OpenAPI Spec

Request Parameters#

logId UUID required

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.attempts Array

An array of attempts for this event.

webhookEventLog.attempts[x].data Object

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

webhookEventLog.attempts[x].endInstant Long

The instant the attempt received a response or timed out.

webhookEventLog.attempts[x].id UUID

The unique Id of this webhook attempt.

webhookEventLog.attempts[x].startInstant Long

The instant the attempt request was sent.

webhookEventLog.attempts[x].webhookCallResponse.exception String

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

webhookEventLog.attempts[x].webhookCallResponse.statusCode Integer

The HTTP status code from the event response.

webhookEventLog.attempts[x].webhookCallResponse.url String

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].webhookId UUID

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.data Object

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

webhookEventLog.event Object

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

webhookEventLog.eventResult String

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.eventType String

The event type. Possible values are:

audit-log.create - When an audit log is created Available since 1.30.0
entity.create - When an entity is created Available since 1.69.0
entity.create.complete - When an entity create transaction has completed Available since 1.69.0
entity.delete - When an entity is deleted Available since 1.69.0
entity.delete.complete - When an entity delete transaction has completed Available since 1.69.0
entity.update - When an entity is updated Available since 1.69.0
entity.update.complete - When an entity update transaction has completed Available since 1.69.0
event-log.create - When an event log is created Available since 1.30.0
jwt.public-key.update - When a JWT signing 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.identity.verified - When a user's identity is verified Available since 1.59.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: To use , you'll need an Enterprise plan.
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: To use , you'll need an Enterprise plan.
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: To use , you'll need an Enterprise plan.
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: To use , you'll need an Enterprise plan.
user.password.breach - When Reactor detects a user is using a potentially breached password (requires an activated license) Available since 1.15.0
Note: To use , you'll need a paid plan.
user.password.reset.send - When a forgot password email has been sent to a user Available since 1.30.0
Note: To use , you'll need an Enterprise plan.
user.password.reset.start - When the process to reset a user password has started Available since 1.30.0
Note: To use , you'll need an Enterprise plan.
user.password.reset.success - When a user has successfully reset their password Available since 1.30.0
Note: To use , you'll need an Enterprise plan.
user.password.update - When a user has updated their password Available since 1.30.0
Note: To use , you'll need an Enterprise plan.
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.challenge - When a user is presented a two-factor challenge Available since 1.68.0
Note: To use , you'll need an Enterprise plan.
user.two-factor.failed-attempt - When a user submits an incorrect answer to a two-factor challenge Available since 1.68.0
Note: To use , you'll need an Enterprise plan.
user.two-factor.method.add - When a user has added a two-factor method Available since 1.30.0
Note: To use , you'll need an Enterprise plan.
user.two-factor.method.remove - When a user has removed a two-factor method Available since 1.30.0
Note: To use , you'll need an Enterprise plan.
user.two-factor.success - When a user submits a correct answer to a two-factor challenge Available since 1.68.0
Note: To use , you'll need an Enterprise plan.
user.update - When a user is updated
user.update.complete - When a user update transaction has completed Available since 1.30.0

webhookEventLog.failedAttempts Integer

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

webhookEventLog.id UUID

The webhook event log unique Id.

webhookEventLog.insertInstant Long

The instant when the Webhook Event Log was created.

webhookEventLog.lastAttemptInstant Long

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

webhookEventLog.lastUpdateInstant Long

The instant when the Webhook Event Log was lasted updated.

webhookEventLog.linkedObjectId UUID

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

webhookEventLog.sequence Long

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

webhookEventLog.successfulAttempts Integer

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}

OpenAPI Spec

Request Parameters#

logId UUID required

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.data Object

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

webhookAttemptLog.endInstant Long

The instant the attempt received a response or timed out.

webhookAttemptLog.id UUID

The unique Id of this webhook attempt.

webhookAttemptLog.startInstant Long

The instant the attempt request was sent.

webhookAttemptLog.webhookCallResponse.exception String

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

webhookAttemptLog.webhookCallResponse.statusCode Integer

The HTTP status code from the event response.

webhookAttemptLog.webhookCallResponse.url String

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.webhookEventLogId UUID

The unique Id for the associated webhook event log.

webhookAttemptLog.webhookId UUID

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#

end Long optional Defaults to current time rounded up to the minute

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

If the current time is 2:01:01, this default would be 2:02:00.

Prior to version 1.57.0 this field did not have a default.

event String optional

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*.

eventResult String optional

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.

eventType String optional

The event type.

numberOfResults Integer optional Defaults to 25

The number of results to return from the search.

orderBy String optional Defaults to insertInstant 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.

Prior to version 1.57.0 this defaults to sequence DESC.

start Long optional Defaults to one hour ago rounded down to the minute

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

If the current time is 2:01:01, this default would be 1:01:00.

Prior to version 1.57.0 this field did not have a default.

startRow Integer optional Defaults 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

OpenAPI Spec

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

Request Body#

search.end Long optional Defaults to current time rounded up to the minute

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

If the current time is 2:01:01, this default would be 2:02:00.

Prior to version 1.57.0 this field did not have a default.

search.event String optional

search.eventResult String optional

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.eventType String optional

The event type.

search.numberOfResults Integer optional Defaults to 25

The number of results to return from the search.

search.orderBy String optional Defaults to insertInstant 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.

Prior to version 1.57.0 this defaults to sequence DESC.

search.start Long optional Defaults to one hour ago rounded down to the minute

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

If the current time is 2:01:01, this default would be 1:01:00.

Prior to version 1.57.0 this field did not have a default.

search.startRow Integer optional Defaults 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].attempts Array

An array of attempts for this event.

webhookEventLogs[x].attempts[x].data Object

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

webhookEventLogs[x].attempts[x].endInstant Long

The instant the attempt received a response or timed out.

webhookEventLogs[x].attempts[x].id UUID

The unique Id of this webhook attempt.

webhookEventLogs[x].attempts[x].startInstant Long

The instant the attempt request was sent.

webhookEventLogs[x].attempts[x].webhookCallResponse.exception String

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

webhookEventLogs[x].attempts[x].webhookCallResponse.statusCode Integer

The HTTP status code from the event response.

webhookEventLogs[x].attempts[x].webhookCallResponse.url String

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].webhookId UUID

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].data Object

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

webhookEventLogs[x].event Object

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

webhookEventLogs[x].eventResult String

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].eventType String

The event type. Possible values are:

audit-log.create - When an audit log is created Available since 1.30.0
entity.create - When an entity is created Available since 1.69.0
entity.create.complete - When an entity create transaction has completed Available since 1.69.0
entity.delete - When an entity is deleted Available since 1.69.0
entity.delete.complete - When an entity delete transaction has completed Available since 1.69.0
entity.update - When an entity is updated Available since 1.69.0
entity.update.complete - When an entity update transaction has completed Available since 1.69.0
event-log.create - When an event log is created Available since 1.30.0
jwt.public-key.update - When a JWT signing 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.identity.verified - When a user's identity is verified Available since 1.59.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: To use , you'll need an Enterprise plan.
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: To use , you'll need an Enterprise plan.
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: To use , you'll need an Enterprise plan.
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: To use , you'll need an Enterprise plan.
user.password.breach - When Reactor detects a user is using a potentially breached password (requires an activated license) Available since 1.15.0
Note: To use , you'll need a paid plan.
user.password.reset.send - When a forgot password email has been sent to a user Available since 1.30.0
Note: To use , you'll need an Enterprise plan.
user.password.reset.start - When the process to reset a user password has started Available since 1.30.0
Note: To use , you'll need an Enterprise plan.
user.password.reset.success - When a user has successfully reset their password Available since 1.30.0
Note: To use , you'll need an Enterprise plan.
user.password.update - When a user has updated their password Available since 1.30.0
Note: To use , you'll need an Enterprise plan.
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.challenge - When a user is presented a two-factor challenge Available since 1.68.0
Note: To use , you'll need an Enterprise plan.
user.two-factor.failed-attempt - When a user submits an incorrect answer to a two-factor challenge Available since 1.68.0
Note: To use , you'll need an Enterprise plan.
user.two-factor.method.add - When a user has added a two-factor method Available since 1.30.0
Note: To use , you'll need an Enterprise plan.
user.two-factor.method.remove - When a user has removed a two-factor method Available since 1.30.0
Note: To use , you'll need an Enterprise plan.
user.two-factor.success - When a user submits a correct answer to a two-factor challenge Available since 1.68.0
Note: To use , you'll need an Enterprise plan.
user.update - When a user is updated
user.update.complete - When a user update transaction has completed Available since 1.30.0

webhookEventLogs[x].failedAttempts Integer

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

webhookEventLogs[x].id UUID

The webhook event log unique Id.

webhookEventLogs[x].insertInstant Long

The instant when the Webhook Event Log was created.

webhookEventLogs[x].lastAttemptInstant Long

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

webhookEventLogs[x].lastUpdateInstant Long

The instant when the Webhook Event Log was lasted updated.

webhookEventLogs[x].linkedObjectId UUID

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

webhookEventLogs[x].sequence Long

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

webhookEventLogs[x].successfulAttempts Integer

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

total Integer

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
    }
  ]
}