How Can We Help?
Introduction
A webhook is a web callback which sends data to the applications. Webhook is used for sending notifications. It is an automated message having a payload and is sent to an unique registered URL. You can connect two different applications using webhook. Whenever an application triggers an event, it sends details to the webhook URL.
Webhook Plugin
You can register a callback URL for an account Id in HEAL. HEAL server should be able to reach the URL. When an event occurs for an account, webhook plugin checks if a callback URL is registered for the account. If an URL is registered, it calls the URL with the payload. Using the registered URL, webhook plugin pushes the events details. Plugin delivers the events at the endpoints. Endpoint needs to be running in your application to receive the events.
Prerequisites
Prerequisites to use the Webhook APIs are as follows:
- Access to HEAL Keycloak server to generate Authorization token.
- Curl must be installed in HEAL keycloak server.
- The identifier of the Account for your Enterprise must be obtained.
Webhook API Request Details
Base URI
Webhook APIs use the following base URI:
- keycloak_host: IP Address or Host name of the server, where Keycloak is installed.
- keycloak_port: Port number on which Keycloak is running.
Request Structure
| HTTP Method | POST, GET, PUT, DELETE |
| Request Header | |
| Authorization Token | Keycloak token from HEAL Server. |
Authorization Token
To generate the Authorization token for the API request header, execute following steps:
- Log in to the HEAL Keycloak Server.
- Execute the following command:
where the value of client_id and grant_type must be replaced with admin-cli and password respectively. Provide HEAL Control Center Admin Username and Password as values of username and password fields.
Example:
Managing Webhook Subscriptions
Creating a Webhook Subscription
Registers a callback URL to receive HEAL events.
API Name – webhook
Format – POST /config/accounts/{accountId}/webhook
Input Json Format
IP address in the url should be IP of the server which receives events from HEAL. Port number should contain the port where the server runs.
Input Parameters
| Type | Name | Description | Schema | Mandatory/Optional |
| Path | accountId | ID or Identifier of an Account | string | Mandatory |
Sample Input
Sample Input Json
Sample Success Response
Retrieving a Webhook Subscription
Fetches the registered callback URL for an account.
API Name – webhook
Format – GET /config/accounts/{accountId}/webhook
Input Parameters
| Type | Name | Description | Schema | Mandatory/Optional |
| Path | accountId | ID or Identifier of an Account | string | Mandatory |
Sample Input
Sample Success Response
Updating a Webhook Subscription
Updates the registered callback URL for an account.
API Name – webhook
Format – PUT /config/accounts/{accountId}/webhook
Input Json Format
Input Parameters
| Type | Name | Description | Schema | Mandatory/Optional |
| Path | accountId | ID or Identifier of an Account | string | Mandatory |
Sample Input
Sample Input Json
Sample Success Response
Deleting a Webhook Subscription
Unregisters the callback URL which was registered earlier for an account.
API Name – webhook
Format – DELETE /config/accounts/{accountId}/webhook
Input Parameters
| Type | Name | Description | Schema | Mandatory/Optional |
| Path | accountId | ID or Identifier of an Account | string | Mandatory |
Sample Input
Sample Success Response
Event Details
Once you register a callback URL for an account in HEAL, your application listening to the events on an endpoint receives following details for an event –
| Field | Description |
| Signal_ID | Unique identifier of the Signal |
| Signal_Type | Type of a Signal. It can be either a Problem or an Early Warning. |
| Signal_Description | Description of the Signal |
| Signal_Status | Open/Upgraded/Closed |
| Severity | Severity of a signal. It can be either Severe or Default |
| App_Names | List of application names affected by the Signal. |
| Related_Signals | Applicable only if Signal_Type is Problem |
| StartTime | Start time of the Signal |
| EndTime | End time of the Signal |
| Username | Name of the HEAL user |
| Organization_Name | Account Name |
| EntryPoint_ServiceName | Name of an entry point service |
| RootCause_ServiceNames | Name of a service which is the root cause of this Signal |
| Affected_ServiceNames | List of affected service names |
| Affected_ApplicationNames | List of affected application names |
| Total_Events | Count of the events occurred |
| Latest_Events | Latest Event ID |
| Latest_Event_Time | Timestamp of the latest event |
| Latest_Events_Detected | Event details of latest detected event |
| A1Protocol | HEAL Protocol |
| A1HostAddress | Host name or IP address of HEAL |
| A1Port | Port number where HEAL server runs |
| AccountIdentifier | Unique identifier of an account in HEAL |