--- title: Configure webhooks description: Use webhooks to send an HTTP POST request to a server when a specific event occurs during an authenticated session, such as a user logging out. component: pingam version: 8.1 page_id: pingam:am-authentication:auth-tree-webhooks canonical_url: https://docs.pingidentity.com/pingam/8.1/am-authentication/auth-tree-webhooks.html keywords: ["Authentication", "REST API", "Setup & Configuration"] page_aliases: ["authentication-guide:auth-tree-webhooks.adoc"] section_ids: create-webhook: Create a webhook example-webhook: Example webhook --- # Configure webhooks Use *webhooks* to send an HTTP POST request to a server when a specific event occurs during an authenticated session, such as a user logging out. Webhooks are used from within authentication trees by the [Register Logout Webhook node](https://docs.pingidentity.com/auth-node-ref/8.1/register-logout-webhook.html). ## Create a webhook 1. In the AM admin UI, go to Realms > *realm name* > Authentication > Webhooks. 1. To create a new webhook, select Create Webhook, specify a webhook name, and click Create. 2. To edit an existing webhook, select the name of the webhook. ![Creating a new authentication webhook.](_images/trees-webhook-create.png) 2. Configure the following settings: * Url Specifies the URL to which the HTTP POST is sent when the event occurs. * Body Specifies the body of the HTTP POST. You can send different formats by also setting the correct Content-Type header in the `Header` property, for example: * **Form Data**. Enter the body value in the format `parameter=value¶meter2=value2`, and set a `Content-Type` header of `application/x-www-form-urlencoded`. * **JSON Data**. Enter the body value in the format `{"parameter":"value","parameter2":"value2"}`, and set a `Content-Type` header of `application/json`. * Headers Specifies any HTTP headers to add to the POST. To add a header, enter the name of the header in the `Key` field, and the value, and click Add (➕). To remove a header, click Delete (✖). The fields in a webhook support variables for retrieving values from the authenticated session after the user has successfully authenticated. Specify a variable in the following format: ``` ${variable_name} ``` To access the type of webhook event, use the `WebhookEventType` parameter key to return one of the following possible values: * `LOGOUT` * `UPGRADE` * `DESTROY` * `MAX_TIMEOUT` * `IDLE_TIMEOUT` For example, to retrieve the event type as a query parameter: `&event=${WebhookEventType}` You can use a variable to access custom properties added to the session with the [Set Session Properties node](https://docs.pingidentity.com/auth-node-ref/8.1/set-session-properties.html) as well as the following default session properties: > **Collapse: Default Session Properties** > > | Property | Example value | Description | > | ---------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | `AMCtxId` | 22e73c81-708e-4849-b064-db29b68ef943-105372 | The audit ID for the session. This is logged as the `trackingIds` field in AM access audit logs. | > | `amlbcookie` | 01 | The cookie that identifies the AM server that generated the session. For environments with multiple AM servers, this can be used for load balancer stickiness. | > | `authInstant` | 2022-02-28T14:06:31Z | The exact time that authentication completed. | > | `AuthLevel` | 5 | The authentication level of the session, determined by the login mechanism used to create the session. For example, a tree can have an authentication level of 10.Step-up authentication is triggered if an authentication level specified by an agent or policy that is designed to protect a resource, is greater than or equal to the value of the `AuthLevel` session property.For more information, see [Session upgrade](../am-sessions/session-upgrade.html). | > | `AuthType` | DataStore | *Not supported*. | > | `CharSet` | UTF-8 | The character set for the session, set to `UTF-8`. | > | `clientType` | genericHTML | The type of client, set to `genericHTML`. | > | `FullLoginURL` | /am/XUI/?realm=%2Falpha | The full login URL, including query parameters. | > | `Host` | 192.0.2.1 | The originating IP address of the authentication request. | > | `HostName` | 192.0.2.1 | The host name that was used when the session was authenticated. | > | `IndexType` | service | Based on the value of the `authIndexValue` query parameter during authentication. Typically, this is set to `service`. | > | `Locale` | en\_US | The session locale. | > | `loginURL` | /am/XUI | The base login URL. A subset of `FullLoginURL`. | > | `OidcSid` | g0wmSpoAIwH6HAwCnurvRcfYqh4 | Unique session ID used by AM to determine whether OIDC ID tokens granted for the same client relate to the same session. This appears when `Enable Session Management` (`storeOpsToken`) is set to true in the OAuth 2.0 provider settings. | > | `Organization` | o=alpha,ou=services,dc=am,dc=example,dc=com | The DN of the realm where authentication took place. | > | `Principal` | id=bjensen,ou=user,o=alpha,ou=services,dc=am,dc=example,dc=com | The value of `sun.am.UniversalIdentifier`. | > | `Principals` | bjensen | The username of the user. *Not supported*. | > | `Service` | Login | The name of the tree that was used to authenticate this session. | > | `successURL` | /am/console | The URL that was redirected to, upon a successful login request. | > | `sun.am.UniversalIdentifier` | id=bjensen,ou=user,o=alpha,ou=services,dc=am,dc=example,dc=com | The DN of the user (username is lowercase). | > | `UserId` | bjensen | The `id` value from the `Principal` property. | > | `UserProfile` | Required | Can be one of: `Required`, `Create`, `Ignore`, or `CreateWithAlias`. Based on the value of the `dynamicProfileCreation` authentication configuration. Values other than `Ignore` indicates that user profile attributes were mapped based on the `User Attribute Mapping to Session Attribute` setting. See [authentication configuration](authn-core-settings.html#authn-core-post-auth) for details.Default: `Required`. | > | `UserToken` | bjensen | The username. | > | `XUSRef` | 8700f1a5-904e-4849-8b2b-cb25296ef453-291173 | If the [cross-upgrade session reference property](../setup/services-configuration.html#global-session-xusref) is enabled, this value identifies the session through its lifecycle. This is logged in the `trackingIds` field in AM audit logs for session creation and upgrade events. | ## Example webhook The following figure shows an example webhook using variable substitutions: ![Example authentication webhook.](_images/trees-webhook-example.png) | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Specifying a variable that isn't present in the user's session puts the literal variable text in the HTTP POST request, for example `user=${UserId}`, rather than `user=bjensen`. |