Breached password detection is a critical component of secure applications.    Read the white paper

FusionAuth logo
FusionAuth logo
  • Features
    FusionAuth Reactor

    FusionAuth Reactor is a powerful suite of features developed to extend FusionAuth's core functionality.

    • Flexible Architecture   Flexible Architecture
    • Auth the Way You Want It   Auth the Way You Want It
    • Security & Compliance   Security & Compliance
    • Ultimate Password Control   Ultimate Password Control
    • Customizable User Experience   Customizable User Experience
    • Advanced Registration Forms   Advanced Registration Forms
    • Built for Devs   Built for Devs
    • User Management & Reporting   User Management & Reporting
    • Scalability   Scalability
    • Breached Password Detection   Breached Password Detection
    • Connectors   Connectors
    • FusionAuth Reactor   FusionAuth Reactor
  • Pricing
  • Docs
  • Downloads
  • Resources
    FusionAuth Resources
    • Upgrade from SaaS
    • Upgrade from Open Source
    • Upgrade from Home Grown
    • Blog   Blog
    • Forum   Forum
    • Community & Support   Community & Support
    • Customer & Partners   Customers & Partners
    • Video & Podcasts   Videos & Podcasts
    • Tech Guides   Getting Started
  • Expert Advice
    Expert Advice for Developers

    Learn everything you need to know about authentication, authorization, identity, and access management from our team of industry experts.

    • Authentication   Authentication
    • CIAM   CIAM
    • Identity Basics   Identity Basics
    • OAuth   OAuth
    • Security   Security
    • Tokens   Tokens
    • Dev Tools   Dev Tools
  • Account
Navigate to...
  • Welcome
  • Getting Started
  • 5-Minute Setup Guide
  • Reactor
  • Core Concepts
    • Overview
    • Users
    • Roles
    • Groups
    • Registrations
    • Applications
    • Tenants
    • Identity Providers
    • Authentication and Authorization
    • Integration Points
    • Roadmap
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cluster
    • Docker
    • Fast Path
    • Kickstart™
    • Homebrew
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Securing
    • Upgrading
  • APIs
    • Overview
    • Authentication
    • Errors
    • Actioning Users
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consent
    • Emails
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Apple
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Twitter
      • OpenID Connect
      • SAML v2
      • External JWT
    • Integrations
    • JWT
    • Keys
    • Lambdas
    • Login
    • Passwordless
    • Registrations
    • Reports
    • System
    • Tenants
    • Themes
    • Two Factor
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • Webhooks
  • Client Libraries
    • Overview
    • Dart
    • Go
    • Java
    • JavaScript
    • .NET Core
    • Node
    • PHP
    • Python
    • Ruby
    • Typescript
  • Themes
    • Overview
    • Localization
    • Examples
  • Email & Templates
    • Overview
    • Configure Email
    • Email Templates
  • Events & Webhooks
    • Overview
    • Events
    • Writing a Webhook
    • Securing Webhooks
  • Example Apps
    • Overview
    • Go
    • Java
    • JavaScript
    • .NET Core
    • PHP
    • Python
    • Ruby
  • Lambdas
    • Overview
    • Apple Reconcile
    • External JWT Reconcile
    • Facebook Reconcile
    • Google Reconcile
    • HYPR Reconcile
    • JWT Populate
    • LDAP Connector Reconcile
    • LinkedIn Reconcile
    • OpenID Connect Reconcile
    • SAML v2 Populate
    • SAML v2 Reconcile
    • Twitter Reconcile
  • Identity Providers
    • Overview
    • Apple
    • Facebook
    • Google
    • HYPR
    • LinkedIn
    • Twitter
    • OpenID Connect
      • Overview
      • Azure AD
      • Github
      • Discord
    • SAML v2
      • Overview
      • ADFS
    • External JWT
      • Overview
      • Example
  • Connectors
    • Overview
    • Generic Connector
    • LDAP Connector
    • FusionAuth Connector
  • Integrations
    • Overview
    • CleanSpeak
    • Kafka
    • Twilio
  • OpenID Connect & OAuth 2.0
    • Overview
    • Endpoints
    • Tokens
  • SAML v2 IdP
    • Overview
    • Google
    • Zendesk
  • Plugins
    • Writing a Plugin
    • Password Encryptors
  • Guides
    • Overview
    • Advanced Registration Forms
    • Breached Password Detection
    • Migration
    • Passwordless
    • Securing Your APIs
    • Silent Mode
  • Tutorials
    • Overview
    • Setup Wizard & First Login
    • Register/Login a User
    • Migrate Users
    • JSON Web Tokens
    • Authentication Tokens
    • Start and Stop FusionAuth
    • Switch Search Engines
    • User Account Lockout
    • Two Factor
  • Reference
    • CORS
    • Configuration
    • Data Types
    • Known Limitations
    • Password Encryptors
  • Release Notes
  • Troubleshooting

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:

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

  • Securing a Webhook - Covers how to ensure your webhooks are secured properly.

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

  • Tenant Settings

  • Add Webhook

  • Test a Webhook

Tenant 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 Tenants → Webhooks to enable events and optionally modify the default transaction level for each event type.

System Webhook Settings

Table columns

Event

The event type, this value will be present in the JSON request to identify the message.

Enabled

When enabled this event can be sent by one or more webhook. You will also need to enable the event for a specific webhook to receive the event.

This toggle allows you to optionally disable an event for all webhooks all at once.

Transaction setting

The transaction setting for this event. This setting will apply to all webhooks consuming this event type.

No Webhooks are required to succeed

The event will succeed regardless of the webhook response status code. Use this setting when it is not important for a webhook to succeed or provide confirmation that the event has been received and processed successfully.

Any single Webhook must succeed

The event will succeed as long as one or more of the webhooks respond with a status code between 200 and 299 (inclusive).

A simple majority of Webhooks must succeed

The event will succeed if at least half of the webhooks respond with a status code between 200 and 299 (inclusive). This means 50% or more of the webhooks must respond successfully.

A two-thirds majority of Webhooks must succeed

The event will succeed if a super majority of the webhooks respond with a status code between 200 and 299 (inclusive). A super majority is two-thirds (66.7%) or more of the configured webhooks.

All of the Webhooks must succeed

The event will succeed if every configured webhook responds with a status code between 200 and 299 (inclusive). Use this setting when it is critical for every configured webhook to receive and process the event before considering it complete.

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.

Webhook Settings

Form Fields

Id Optional

An optional UUID. When this value is omitted a unique Id will be generated automatically.

URL Required

The endpoint that FusionAuth will used to send JSON events.

Connect timeout Required defaults to 1000 or 1 second

The HTTP connect timeout in milliseconds used when connecting to the provided URL.

Read timeout Required defaults to 2000 or 2 seconds

The HTTP read timeout in milliseconds used when connecting to the provided URL.

Description Optional

An optional description of this webhook.

Events

Form Fields

Event type

The event type that will be provided in the JSON event.

Enabled

This toggle indicates if the event is enabled and may be sent to configured webhooks. This toggle affects all webhooks, a specific webhook may still be configured to ignore this event.

Security

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

Webhook Settings - Security

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

Webhook Settings - All applications Webhook Settings - Select Applications

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

Webhook Settings - HTTP Headers

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.

Webhook Test

Form Fields

URL Read-Only

The URL of the webhook you are testing. If you wish to test a different webhook return to the webhook menu and select the test action on another webhook.

Event type

The selected event type to send to the webhook.

Event

The JSON event to send to the webhook. This is a generated example and it may be modified before sending to replicate a specific scenario.

Related Posts

  • Breached Password Detection: How to Lock User Accounts with a Webhook
  • Using Webhooks In FusionAuth To Delete User Data

Quick Links

  • Download
  • Pricing
  • Enterprise Sales FAQ
  • Contact Us
  • Jobs (come work with us)
  • My Account

Resources

  • Docs
  • Blog
  • Community & Support
  • Upgrade from SaaS
  • Upgrade from Homegrown
  • Upgrade from Open Source

Everything Else

  • Privacy Policy
  • Product Privacy Policy
  • License
  • License FAQ
  • Security (contact, bug bounty, etc)
  • Technical Support

Connect with Us

logo
Subscribe for Updates
We only send dev friendly newsletters. No marketing fluff!
© 2020 FusionAuth