# Create a Webhook API API documentation for the FusionAuth Create a Webhook API. > For the index of this section of the site, see [llms.txt](https://fusionauth.io/docs/llms.txt) This API is used to create a Webhook. Specifying an Id on the URI will instruct FusionAuth to use that Id when creating the Webhook. Otherwise, FusionAuth will create a Id for the Webhook automatically. ## Request [Global API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#global-api-key-authentication) Create a Webhook without providing an Id. An Id will be automatically generated. `POST /api/webhook` [Global API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#global-api-key-authentication) Create a Webhook with the given Id. `POST /api/webhook/{webhookId}` ### Request Parameters `webhookId` * UUID * optional * Defaults to secure random UUID * Immutable The Id to use for the new Webhook. If not specified a secure random UUID will be generated. #### Request Body `webhook.applicationIds` * Array * optional * Deprecated The Ids of the Applications that this Webhook should be associated with. If no Ids are specified and the **global** field is `false`, this Webhook will not be used. Typically **global** should be set to `true`. Removed in 1.37.0 In version 1.37.0 and beyond, Webhooks are optionally associated with Tenants instead of Applications. See new field **tenantIds**. `webhook.connectTimeout` * Integer * required The connection timeout in milliseconds used when FusionAuth sends events to the Webhook. `webhook.data` * Object * optional * Available since 1.15.0 An object that can hold any information about the Webhook that should be persisted. `webhook.description` * String * optional A description of the Webhook. This is used for display purposes only. `webhook.eventsEnabled` * Object * optional A mapping for the events that are enabled for this Webhook. The key of the Object property is the name of the event and the value is a boolean. It should look like this: ```json { "user.create": true, "user.delete": false } ``` The possible event types 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` `webhook.global` * Boolean * optional * Defaults to false Whether or not this Webhook is used for all Tenants or just for specific Tenants. > **VERSION:** Whether or not this Webhook is used for all events or just for specific Applications. In almost all cases you want to set this field to `true` and filter on the application Id when processing the webhook. `webhook.headers` * Map * optional An object that contains headers that are sent as part of the HTTP request for the events. `webhook.httpAuthenticationPassword` * String * optional The HTTP basic authentication password that is sent as part of the HTTP request for the events. `webhook.httpAuthenticationUsername` * String * optional The HTTP basic authentication username that is sent as part of the HTTP request for the events. `webhook.readTimeout` * Integer * required The read timeout in milliseconds used when FusionAuth sends events to the Webhook. `webhook.signatureConfiguration.enabled` * Boolean * optional * Defaults to false * Available since 1.48.0 Whether or not webhook events are signed. `webhook.signatureConfiguration.signingKeyId` * UUID * optional * Defaults to false * Available since 1.48.0 The Id of the key used to sign webhook events. Required when **webhook.signatureConfiguration** is set to `true`. `webhook.sslCertificate` * String * optional * Deprecated An SSL certificate in PEM format that is used to establish the SSL (TLS specifically) connection to the Webhook. Deprecated since `1.48.0` In version 1.48.0 and beyond, the webhook SSL certificate can be managed via **webhook.sslCertificateKeyId**. This field is not allowed on a request when **webhook.sslCertificateKeyId** is provided. `webhook.sslCertificateKeyId` * UUID * optional * Available since 1.48.0 The Id of an existing [Key](https://fusionauth.io/docs/apis/keys.md). The X.509 certificate is used for client certificate authentication in requests to the Webhook. `webhook.tenantIds` * Array * optional * Available since 1.37.0 The Ids of the Tenants that this Webhook should be associated with. If no Ids are specified and the **global** field is `false`, this Webhook will not be used. `webhook.url` * String * required The fully qualified URL of the Webhook's endpoint that will accept the event requests from FusionAuth. *Example Request JSON* ```json { "webhook": { "connectTimeout": 1000, "data": { "updatedBy": "richard" }, "description": "The standard game Webhook", "eventsEnabled": { "user.create": true, "user.delete": false }, "global": false, "headers": { "Header 1": "value 1", "Header 2": "value 2" }, "httpAuthenticationPassword": "password", "httpAuthenticationUsername": "username", "readTimeout": 2000, "signatureConfiguration": { "enabled": true, "signingKeyId": "401c9046-b274-403f-963d-adc5024c6ef0" }, "sslCertificateKeyId": "e31e242b-4eca-4309-921f-48cb72ec9bfb", "tenantIds": [ "32306536-3036-6431-3865-646430303332", "30663132-6464-6665-3032-326466613934" ], "url": "http://mygameserver.local:7001/fusionauth-webhook" } } ``` ## Response The response for this API contains the information for the Webhook that was created. *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](https://fusionauth.io/docs/apis/errors.md) 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](https://fusionauth.io/docs/apis/authentication.md). | | 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. | | 503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. | ### Response Body `webhook.applicationIds` * Array * optional * Deprecated The Ids of the Applications that this Webhook is associated with. If no Ids are returned and the **global** field is `false`, this Webhook is not used. Typically **global** should be set to `true`. Removed in 1.37.0 In version 1.37.0 and beyond, Webhooks are optionally associated with Tenants instead of Applications. See new field **tenantIds**. `webhook.connectTimeout` * Integer The connection timeout in milliseconds used when FusionAuth sends events to the Webhook. `webhook.data` * Object * Available since 1.15.0 An object that can hold any information about the Webhook that should be persisted. `webhook.description` * String A description of the Webhook. This is used for display purposes only. `webhook.eventsEnabled` * Object A mapping for the events that are enabled for this Webhook. The key of the Object property is the name of the event and the value is a boolean. It should look like this: ```json { "user.create": true, "user.delete": false } ``` The possible event types 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` `webhook.global` * Boolean Whether or not this Webhook is used for all Tenants or just for specific Tenants. > **VERSION:** Whether or not this Webhook is used for all events or just for specific Applications. `webhook.headers` * Map An object that contains headers that are sent as part of the HTTP request for the events. `webhook.httpAuthenticationPassword` * String The HTTP basic authentication password that is sent as part of the HTTP request for the events. `webhook.httpAuthenticationUsername` * String The HTTP basic authentication username that is sent as part of the HTTP request for the events. `webhook.id` * UUID The Id of the Webhook. `webhook.insertInstant` * Long The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Webhook was added to the FusionAuth database. `webhook.lastUpdateInstant` * Long The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Webhook was last updated in the FusionAuth database. `webhook.readTimeout` * Integer The read timeout in milliseconds used when FusionAuth sends events to the Webhook. `webhook.signatureConfiguration.enabled` * Boolean * Defaults to false Whether or not webhook events are signed. `webhook.signatureConfiguration.signingKeyId` * UUID * optional The Id of the key used to sign webhook events. `webhook.sslCertificate` * String * Deprecated An SSL certificate in PEM format that is used to establish the SSL (TLS specifically) connection to the Webhook. Deprecated since `1.48.0` In version 1.48.0 and beyond, the webhook SSL certificate can be managed via **webhook.sslCertificateKeyId**. `webhook.sslCertificateKeyId` * UUID * Available since 1.48.0 The Id of an existing [Key](https://fusionauth.io/docs/apis/keys.md). The X.509 certificate is used for client certificate authentication in requests to the Webhook. `webhook.tenantIds` * Array * optional * Available since 1.37.0 The Ids of the Tenants that this Webhook is associated with. If no Ids are returned and the **global** field is `false`, this Webhook is not used. `webhook.url` * String The fully qualified URL of the Webhook's endpoint that will accept the event requests from FusionAuth. *Example Response JSON for a Single Webhook* ```json { "webhook": { "connectTimeout": 1000, "data": { "updatedBy": "richard" }, "description": "The standard game Webhook", "eventsEnabled": { "user.create": true, "user.delete": false }, "global": false, "headers": { "Header 1": "value 1", "Header 2": "value 2" }, "httpAuthenticationPassword": "password", "httpAuthenticationUsername": "username", "id": "00000000-0000-0000-0000-000000000042", "insertInstant": 1471786482322, "lastUpdateInstant": 1595361143101, "readTimeout": 2000, "signatureConfiguration": { "enabled": true, "signingKeyId": "401c9046-b274-403f-963d-adc5024c6ef0" }, "sslCertificateKeyId": "e31e242b-4eca-4309-921f-48cb72ec9bfb", "tenantIds": [ "32306536-3036-6431-3865-646430303332", "30663132-6464-6665-3032-326466613934" ], "url": "http://mygameserver.local:7001/fusionauth-webhook" } } ``` --- ## Other pages in Webhooks > For the full index of this section, see [Apis](https://fusionauth.io/docs/llms-apis.txt). - [Delete a Webhook API](https://fusionauth.io/docs/apis/webhooks/delete-a-webhook.md): API documentation for the FusionAuth Delete a Webhook API. - [Webhook API](https://fusionauth.io/docs/apis/webhooks.md): Learn about the APIs for creating, retrieving, updating and deleting Webhooks. - [Retrieve a Webhook API](https://fusionauth.io/docs/apis/webhooks/retrieve-a-webhook.md): API documentation for the FusionAuth Retrieve a Webhook API. - [Search for Webhooks API](https://fusionauth.io/docs/apis/webhooks/search-for-webhooks.md): API documentation for the FusionAuth Search for Webhooks API. - [Update a Webhook API](https://fusionauth.io/docs/apis/webhooks/update-a-webhook.md): API documentation for the FusionAuth Update a Webhook API.