How do I configure webhooks to notify user sign-up and application requests to an external approval system?

About this task

You can use webhooks to send user sign-up requests, application requests to any external approval system.

This use case starts when you want to configure an external approval onboarding strategy and ends when you have completed the configuration.

To configure webhooks

Click the menu options icon from the title bar and click Administration.
Click Webhooks from the left pane and click Create.
Provide the external approval system endpoint URL in the field.
Select System from the Type list.
Provide the required Security preference.
Available options are:
- Basic. Indicates the basic credentials are required. Provide your user name and password.
- None. Indicates that no authentication is required.
Select EXTERNAL_VERIFICATION from the Event type list.
Click Save.
Your changes are saved.

The webhook is added. Notifications for the selected events are triggered and sent to the specified endpoint.

Next steps - Configuring external approval for user sign-up requests:

When there is a user sign-up request, the user details are sent to the configured URL.
Sample request
```
{
  "created" : "2022-02-09T13:37+0000",
  "documentType" : "EVENTS",
  "parameters" : {
    "details" : {
      "email" : "johnsmith@gmail.com",
    },
    "source" : "ExternalVerificationExecutor",
    "link_id" : "8688ae09-243b-4589-bea1-48cb53d9e702"
  },
  "type" : "EXTERNAL_VERIFICATION_EVENT"
}
```
The parameters.details section in the payload has the newly signed up user information. Approvers check this data to approve or reject a sign-up request. By default, the Sign up page displays the Email and Password fields. If you add other fields, the data entered by users is included in the parameters.details section of the payload.
The external system processes the new user sign-up request, and approves or rejects the request. The external system must specify the link_id value received through the payload and approve or reject the requests using the following REST resources:
- PUT /rest/v1/approvals/request/external/link_id/approve. Approves the specified external approval request.
- PUT /rest/v1/approvals/request/external/link_id/approve?comments=comments. Approves the specified external approval request with comments.
- PUT /rest/v1/approvals/request/external/link_id/reject. Rejects the specified external approval request.
- PUT /rest/v1/approvals/request/external/link_id/reject?comments=comments. Rejects the specified external approval request with comments.

Next steps - Configuring external approval for application creation or application scope increase requests:

When there is an application creation request, the application details are sent to the configured URL.

Sample request

{
  "created" : "2022-02-10T06:15+0000",
  "documentType" : "EVENTS",
  "parameters" : {
    "details" : {
      "user_request_id" : "25fb94d9-6d30-4515-aa14-65177484946b",
      "user" : "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
      "application_id" : "c02532b9-fd99-488f-98bb-b9c85fd081db"
    },
    "source" : "ExternalVerificationExecutor",
    "link_id" : "ff4e6597-1a86-4997-832a-38544d66632f"
  },
  "type" : "EXTERNAL_VERIFICATION_EVENT"
}

As a system administrator, you can get additional details about the request using the following REST call with required request Id:

GET	 /rest/v1/requests/requestId

The parameters.details.user_request_id section in the payload has the request Id. The sample response of the payload with additional details:

{
    "owner": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
    "id": "25fb94d9-6d30-4515-aa14-65177484946b",
    "documentType": "USER_REQUEST",
    "type": "APPLICATION_CREATION_REQUEST",
    "status": "APPROVAL_PENDING",
    "context": {
        "apis": [
            "934d1e01-4dca-11ec-43ed-8eb69da50747"
        ],
        "custom": {},
        "name": "MyApp",
        "description": null,
        "redirect_uris": [
            "https://host.com/rest/v1/oauth/callback"
        ],
        "subscription": "false",
        "externalrefkey": "656ef5dc-53dd-4b33-8407-42da59781382",
        "user": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
        "tenant": "default",
        "provider_ref": "13b6dac1-9ed7-11eb-5403-2692ff6904c7"
    },
    "application": "c02532b9-fd99-488f-98bb-b9c85fd081db",
    "state": {
        "4cf77aca-d721-40b1-bc27-0cb0b7bd0a6d": "APPROVAL_PENDING"
    }
}

View the details of the API associated with an application by making a REST call to the following endpoint with the required API Id:
```
GET	 /rest/v1/apis/id
```
View the details of the user who created an application by making a REST call to the following endpoint with the required user Id:
```
GET	 /rest/v1/users/id
```
View the details of an audit event by making a REST call to the following endpoint with the required event Id:
```
GET	 /rest/v1/events/id
```

The external system processes the application request, and approves or rejects the request. The external system must specify the link_id value received through the payload and approve or reject the requests using the following REST resources:
- PUT /rest/v1/approvals/request/external/link_id/approve. Approves the specified external approval request.
- PUT /rest/v1/approvals/request/external/link_id/approve?comments=comments. Approves the specified external approval request with comments.
- PUT /rest/v1/approvals/request/external/link_id/reject. Rejects the specified external approval request.
- PUT /rest/v1/approvals/request/external/link_id/reject?comments=comments. Rejects the specified external approval request with comments.

Next steps - Configuring external approval for package subscription requests

When there is a package subscription request, the subscription details are sent to the configured URL.

Sample request

{
  "created" : "2022-02-10T06:15+0000",
  "documentType" : "EVENTS",
  "parameters" : {
    "details" : {
      "user_request_id" : "7022738e-8367-48bf-a60a-6015409a129a",
      "user" : "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
      "application_id" : "45f6073c-4e5c-49d2-80cb-13218f228014"
    },
    "source" : "ExternalVerificationExecutor",
    "link_id" : "ff4e6597-1a86-4997-832a-38544d66632f"
  },
  "type" : "EXTERNAL_VERIFICATION_EVENT"
}

As a system administrator, you can get additional details about the request using the following REST call with required request Id:

GET	 /rest/v1/requests/requestId

The parameters.details.user_request_id section in the payload has the request Id. The sample response of the payload with additional details:

{
    "owner": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
    "id": "7022738e-8367-48bf-a60a-6015409a129a",
    "documentType": "USER_REQUEST",
    "type": "SUBSCRIPTION_CREATION_REQUEST",
    "status": "APPROVAL_PENDING",
    "context": {
        "package": "dc43a88a-7de5-4d88-960d-912f8e82b44d",
        "custom": {},
        "name": "PackageSubscription",
        "description": null,
        "redirect_uris": [
            "http://hostname/portal/rest/v1/oauth/callback"
        ],
        "subscription": "true",
        "plan": "4b780d62-dc26-44cb-81d3-02e86204c3db",
        "user": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
        "tenant": "default",
        "provider_ref": "01719942-6ed5-4f6f-a000-1f4807e8b711"
    },
    "application": "45f6073c-4e5c-49d2-80cb-13218f228014",
    "state": {
        "4956cf28-b8c3-4a4f-969d-1a8baa1754ef": "APPROVAL_PENDING"
    }
}

View the details of the subscribed package by making a REST call to the following endpoint with the required package Id:
```
GET	 /rest/v1/packages/id
```
View the details of the subscribed plan by making a REST call to the following endpoint with the required plan Id:
```
GET	 /rest/v1/plans/id
```
View the details of an audit event by making a REST call to the following endpoint with the required event Id:
```
GET	 /rest/v1/events/id
```
View the details of the user who created a subscription by making a REST call to the following endpoint with the required user Id:
```
GET	 /rest/v1/users/id
```

The external system processes the subscription request, and approves or rejects the request. The external system must specify the link_id value received through the payload and approve or reject the requests using the following REST resources:
- PUT /rest/v1/approvals/request/external/link_id/approve. Approves the specified external approval request.
- PUT /rest/v1/approvals/request/external/link_id/approve?comments=comments. Approves the specified external approval request with comments.
- PUT /rest/v1/approvals/request/external/link_id/reject. Rejects the specified external approval request.
- PUT /rest/v1/approvals/request/external/link_id/reject?comments=comments. Rejects the specified external approval request with comments.