Events & Webhook Overview

Overview

Events and Webhooks are a core architecture feature of FusionAuth. This feature provides a publish-subscribe pattern to developers and integrators of FusionAuth. In this architecture pattern, the Webhook is the subscriber and FusionAuth is the publisher.

This system is designed to provide feedback to your system when events occur within FusionAuth. Events are sent via an HTTP POST request with a JSON request body. The request will be sent with the a Content-Type header of application/json. This is the same style of API that the FusionAuth App uses to handle API requests from your application.

See the corresponding Webhook APIs if you’d prefer to programatically configure FusionAuth Webhooks.

Here are the topics in this section:

• Events - Covers all of the event types that FusionAuth sends to Webhooks

• Writing a Webhook - Covers how to write a Webhook that will process events from FusionAuth.

Continue reading below to see how the events and webhooks are configured using the FusionAuth user interface.

• System Settings

• Add Webhook

• Test a Webhook

System Settings

To prepare to consume FusionAuth events you’ll first need to enable the event globally and select a transaction level that is compatible with your requirements. Navigate to Settings System Webhooks to enable events and optionally modify the default transaction level for each event type.

Add Webhook

After you have enabled the events that you will be using, create a webhook definition to indicate where FusionAuth should send the JSON events. Navigate to Settings Webhooks to create a new webhook.

See the example screenshot below, at a minimum you will need to provide the URL the endpoint that will accept the FusionAuth JSON events. You can see in this screenshot that even though an event may be enabled globally you can still select which events will be sent to this webhook.

If you need to configure an Authorization header or other credentials to allow FusionAuth to make a request to your webhook, you may do so in the Security tab.

Security

The security settings may be used to require authentication in order to submit an event to the webhook.

Table 4. Form Fields

Basic auth username Optional	The username to be used for HTTP Basic Authentication.
Basic auth password Optional	The password to be used for HTTP Basic Authentication.
Certificate Optional	The SSL certificate in PEM format to be used when connecting to the webhook. When provided an in memory keystore will be generated in order to complete the https connection to the webhook.

Applications

Table 5. Form Fields

All applications

When this toggle is enabled, all events will be sent to this webhook, events for a specific application.

Applications

When the All applications is disabled, this field will be exposed. Select the application for which you would like to receive events. Not all events are considered application specific and selecting an application will limit you to only receiving application events. The following events are considered Application events: jwt.public-key.update jwt.refresh-token.revoke user.action In most cases you will want to use the All applications configuration.

Headers

Table 6. Form Fields

Name	The name of the header to add to the HTTP request when sending the event to the webhook
Value	The header value to add to the HTTP request when sending the event to the webhook

Test a Webhook

Once you have a webhook up and running and configured to receive JSON events from FusionAuth you may wish to test it by sending different events. FusionAuth has built in a test capability to allow you to construct any event and send it to your webhook.

Navigate to Settings Webhooks and select the purple icon for the webhook you wish to test. Select the event type to test, optionally modify the JSON to test a specific scenario and then use the send button in the top right to send the event to the webhook.