Web hooks configuration API

The web hooks configuration API allows the maintenance of the web hook definitions that can be later used by the OAuth clients. The web hooks can serve different purposes ranging from making access decisions to user details manipulation.

All endpoints are protected with the API client credentials (either Client Secret Basic or PrivateKeyJWT depending on the client's authentication method).

The web hooks configuration API is an admin API and requires an API client with the onegini_api_admin scope.

Endpoints

List web hook configurations

This returns a list of all web hook configurations. The password is never returned with the response.

• Endpoint: /api/v1/configuration/web-hooks
• Method: GET

Example request:

GET /api/v1/configuration/web-hooks HTTP/1.1
Host: example.onewelcome.com

Example success response:

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
   "result":[
      {
         "id":"c7b34d6a-682e-4eb2-8d1d-af2842108867",
         "type":"DABP",
         "name":"Delegated Administration Web Hook production cluster",
         "base_uri":"https://dabp-prod.onewelcome.com",
         "authentication_method":"JWT"
      },
      {
        … more Web Hook configurations …
      }
   ]
}

In the event of an error, one of the generic error codes is returned.

Create Web Hook configuration

This creates a Web Hook configuration from scratch

• Endpoint: /api/v1/configuration/web-hooks
• Method: POST

JSON body parameters:

Example request:

POST /api/v1/configuration/web-hooks HTTP/1.1
Host: example.onewelcome.com
Content-Type: application/json
{
   "id":"c7b34d6a-682e-4eb2-8d1d-af2842108867",
   "type:"USER_DETAILS_CUSTOMIZATION",
   "name":"User Details Customization Web Hook",
   "base_uri":"https://customize-user-details.onewelcome.com",
   "authentication_method": "NONE"
}

Example success response:

HTTP/1.1 201 CREATED
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Location: /api/v1/configuration/web-hooks/c7b34d6a-682e-4eb2-8d1d-af2842108867

Example request:

POST /api/v1/configuration/web-hooks HTTP/1.1
Host: example.onewelcome.com
Content-Type: application/json
{
   "id":"c7b34d6a-682e-4eb2-8d1d-af2842108868",
   "type:"CUSTOMIZE_TOKEN",
   "name":"Customize Token Web Hook",
   "base_uri":"https://customize-token.onewelcome.com",
   "authentication_method": "NONE"
}

Example success response:

HTTP/1.1 201 CREATED
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Location: /api/v1/configuration/web-hooks/c7b34d6a-682e-4eb2-8d1d-af2842108868

The success response body is empty. The Location header contains the URL for this new API client.

In the event of an error, one of the generic error codes is returned.

Read web hook configuration

This returns a web hook configuration. The sensitive authentication credentials like password are never returned with the response.

• Endpoint: /api/v1/configuration/web-hooks/{id}
• Method: GET

Path parameters:

Example request:

GET /api/v1/configuration/web-hooks/c7b34d6a-682e-4eb2-8d1d-af2842108867 HTTP/1.1
Host: example.onewelcome.com

Example success response:

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
   "id":"c7b34d6a-682e-4eb2-8d1d-af2842108867",
   "type":"DABP",
   "name":"Delegated Administration production cluster",
   "base_uri":"https://dabp-prod.onewelcome.com",
   "authentication_method":"JWT",
   "username": "dabp_user"
}

In the event of an error, one of the generic error codes is returned.

Update web hook configuration

Some fields can be updated after creating a web hook configuration.

• Endpoint: /api/v1/configuration/web-hooks/{id}
• Method: PATCH

Path parameters:

JSON body parameters:

Only the fields that are sent in the request are changed.

Example request:

PATCH /api/v1/configuration/web-hooks/c7b34d6a-682e-4eb2-8d1d-af2842108867 HTTP/1.1
Host: example.onewelcome.com
Content-Type: application/json

{
  "password":"F167433E63CE8BD874D7F167433E63CE8BD874D7"
}

Example success response:

HTTP/1.1 204 NO CONTENT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

The success response body is empty.

In the event of an error, one of the generic error codes is returned.

Delete web hook configuration

This removes a web hook configuration. This also removes any link to this configuration, such as from the web client or application configuration.

• Endpoint: /api/v1/configuration/web-hooks/{id}
• Method: DELETE

Path parameters:

Example request:

DELETE /api/v1/configuration/web-hooks/c7b34d6a-682e-4eb2-8d1d-af2842108867 HTTP/1.1
Host: example.onewelcome.com

Example success response:

HTTP/1.1 204 NO CONTENT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

In the event of an error, one of the generic error codes is returned.

Error codes

One of the following responses is returned, containing a JSON object with an error code, a message, and details about the error.

Authentication methods

JWT

JSON Web Tokens (JWT) are the preferred authentication method. JWT is a reliable, secure method of representing claims to be transferred between two parties.

The following is an example JWT that the OneWelcome Identity Platform generates for use in web hooks:

{
  "aud": "http://wiremock:8080",
  "sub": "onewelcomeAccessWebHookClient",
  "scope": "onewelcome_webhooks onewelcome_webhook_test",
  "iss": "https://playground.test.onewelcome.io/oauth",
  "exp": 1705585175,
  "jti": "AT.4027b2b3-b3f8-4ff9-bef7-c7a0f01d6bec",
  "client_id": "onewelcomeAccessWebHookClient",
  "cid": "onewelcomeAccessWebHookClient"
}

• aud (Audience): Specifies the recipients that the JWT is intended for. It contains the base_uri from the web hook configuration.

• sub (Subject): Identifies the subject of the JWT. In this case, it represents the identity of the web hook client named onewelcomeAccessWebHookClient.

• scope: Defines the permission scope granted to the web hook client. It contains two space-delimited scopes: a fixed onewelcome_webhooks scope, and a scope based on the name of the web hook onewelcome_webhook_<name>, where <name> will be replaced with the lower-case web hook name and space characters are replaced with the underscore sign. For example, a web hook named My WebHook will contain onwewelcome_webhook_my_webhook scope.

• iss (Issuer): Identifies the principal that issued the JWT. It contains the URL of the OneWelcome Identity Platform service that calls the web hook.

• exp (Expiration time): Specifies the expiration time after which the JWT must not be accepted for processing. It is a numeric value representing the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date and time. Issued tokens are valid for 15 minutes and can be cached and reused by the OneWelcome Identity Platform for performance reasons.

• jti (JWT ID): Provides a unique identifier for the JWT, which can be used to prevent the JWT from being replayed. It is a case-sensitive string.

• client_id (Client ID): Identifies the client that requested the JWT. It contains a fixed value onewelcomeAccessWebHookClient.

• cid (Client ID, deprecated): Same as client_id

Tokens are signed by the OneWelcome Idenntity Platform and can be verified by using public keys available at: <value_of_iss_claim>/v1/keys, such as https://customer.onewelcome.io/oauth/v1/keys.

Basic authentication (deprecated)

Basic authentication is a simple authentication scheme built into the HTTP protocol. The client sends a base64-encoded string that contains a username and a password separated by a colon :. This string is added to the header of the HTTP request in the Authorization field with Basic as a type.

For example: Authorization: Basic encoded_username_and_password

The server then decodes the base64 string and authenticates the request based on these credentials.

Despite its simplicity, basic authentication is seen as insecure for most web applications because the username and password are sent across the network in plaintext (albeit base64-encoded) and can easily be intercepted. It is vulnerable to man-in-the-middle attacks, and for this reason, a safer alternative is JWT.

No authentication

No authentication means there are no special encoding, keys, or credentials needed to access the API or web hook. Any API calls made do not require any token or basic authentication.

No Authentication is often used in public APIs or public resources where restricting access is not necessary.

However, while it's the easiest to implement, No Authentication provides no security because it allows anyone to access and interact with your API or web hook. It is not recommended for any operations involving sensitive data, and should only be used sparingly, with a full understanding of its implications.