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.

Here’s a brief video covering some aspects of webhooks:

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

Here are the topics in this section:

• Writing a Webhook - Covers how to write a Webhook that will process events from FusionAuth.
• Securing a Webhook - Covers how to ensure your webhooks are secured properly.
• Signing a Webhook - Covers how to sign webhook events
• Events - Covers all of the event types that FusionAuth sends to Webhooks

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

Tenant Settings

To prepare to consume FusionAuth events you’ll first need to enable the event and select a transaction level that is compatible with your requirements in the tenant.

To do so, navigate to Tenants -> Webhooks to enable events and optionally modify the default transaction level for each event type.

Webhooks

Event Settings

Transaction Failures

As mentioned above, if you configure your transaction settings to require one or more webhooks to succeed, success occurs if the requisite number of webhooks returns a status code between 200 and 299.

If they do not, however, the webhook transaction fails. When this occurs, any API calls you are making will receive a response with the status code 504.

The response will be a JSON object with more details:

Example Error Response JSON

{
  "generalErrors": [
     {
	"code": "[WebhookTransactionException]",
	"message": "One or more webhooks returned an invalid response or were unreachable. Based on your transaction configuration, your action cannot be completed."
      }
   ]
}

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.

Form Fields

Events

Form Fields

Security

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

Form Fields

Tenants

Here’s the configuration when a webhook will be sent for all tenants.

Here’s the configuration when a webhook should be sent for certain tenants.

Form Fields

The exceptions to this are the following system events which are not tenant specific:

• audit-log.create
• event-log.create
• kickstart.success

These events are configured at the system level and cannot be scoped to a certain tenant.

Headers

Form Fields

Applications

Prior to version 1.37.0 these events could be application scoped:

• jwt.public-key.update
• jwt.refresh-token.revoke
• user.action

Form Fields

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.

Modifications to event JSON will be preserved across tests. If you want to reset the JSON for a given event, select that event and click the Reset button.

Form Fields

FAQs

Q: I have successfully tested my Webhook, but why am I not receiving specific live events?

A: In order to receive events to your webhook endpoint, ensure the following items are configured:

• Set up the Tenant events. Navigate to Tenants -> Webhooks and enable the specific events.
• Set up Webhook tenants. Navigate to Settings -> Webhooks -> Tenants and ensure the Webhook is configured either for All tenants or your desired tenant or tenants.
• Set up the Webhook events. Navigate to Settings -> Webhooks -> Events and ensure the specific events are enabled for the Webhook.

Unless all three of these configurations are correct, you won’t receive events to your configured endpoint.