FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    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 and select a transaction level that is compatible with your requirements.

    You do not need to configure the tenant settings for any instance level webhooks, such as the Audit Log Create.

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

    Tenant Configuration - Webhooks

    Webhooks

    Webhooks

    Enable the webhooks you wish to receive events from this tenant. All webhooks will be shown, but if the webhook is a global webhook then you will not be able to unselect it here. That must be done in the Webhook Settings

    Event Settings

    Event

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

    Description

    The description of the event.

    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.

    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.

    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

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

    Description

    The description of the event.

    System

    A check indicates this event is a system event and is not scoped to a tenant.

    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.

    Tenants

    Available since 1.37.0

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

    Webhook Settings - All applications

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

    Webhook Settings - Select Applications

    Form Fields

    All tenants

    When this toggle is enabled, events for all tenants will be sent to this webhook.

    Tenants

    When the All tenants setting is disabled, this field will be exposed. Select the tenants for which you would like to receive events.

    Most events are considered tenant specific. Selecting one more more tenants will cause FusionAuth to send events only for those tenants.

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

    • audit-log.create

    • event-log.create

    • kickstart.success

    These events are configured at the instance level and cannot be limited to a certain tenant.

    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

    Applications

    This documentation is for versions earlier than 1.37.0. Application scoped events are not supported on versions later than 1.37.0. If you are on a version earlier than 1.37.0 and you want to get events for certain applications, the preferred method is to send events for a tenant. Filter on the applicationId when consuming the event and discard events from any applications not of interest.

    Please don’t use application scoped webhook functionality.

    Prior to version 1.37.0 these events could be application scoped:

    • jwt.public-key.update

    • jwt.refresh-token.revoke

    • user.action

    Webhook Settings - All applications Webhook Settings - Select Applications

    Form Fields

    All applications Deprecated

    When this toggle is enabled, all events will be sent to this webhook.

    Removed in version 1.37.0 In version 1.37.0 and beyond, webhooks are scoped to tenants.

    Applications Deprecated

    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.

      Removed in version 1.37.0 In version 1.37.0 and beyond, webhooks are global or are scoped to tenants.

    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

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    Subscribe for developer updates