# Webhook

## Introduction

A webhook (also called a web callback or HTTP push API) is a **way for an app to provide other applications with real-time information**. A webhook delivers data to other applications as it happens, meaning you get data immediately.

For using webhook service clients have to register an API application that will have an API key, api-admin credential, and an encryption file for further authentications. This is taken place for a successful webhook event subscription validation. For implementing the webhook service follow the given steps. 

Available webhook event slugs and their provided data are listed at the end of the webhook document.

## List Events

## List Provided Webhook Events

<mark style="color:blue;">`GET`</mark> `‎https://<domain>/<api prefix>/<version>/webhook/list/events/`

This API endpoint provided a list of available webhook events.

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| apikey<mark style="color:red;">\*</mark>        | string | Apikey              |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

{% tabs %}
{% tab title="200: OK " %}

```html
HTTP/1.1 200 OK
Content-Type: application/json
{
    "status_code": 200,
    "errors": {},
    "data": {
        "results": [
            {
                "id": <id>,
                "slug": "<event_slug>",
                "name": "<event_name>",
                "trigger_immediate": <trigger_immediate>,
                "is_active": <is_active_status>
            },
            ...
        ],
        "count": <list_count>,
        "previous": <previous_page_url>,
        "next": <next_page_url>
    }
}
```

{% endtab %}
{% endtabs %}

#### Sample Code

**Node**

```javascript
var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://<domain>/<api prefix>/<version>/webhook/list/events/',
  'headers': {
    'apikey': '<apikey>',
    'Authorization': 'Bearer <access-token>'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

**PHP**

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<domain>/<api prefix>/<version>/webhook/list/events/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'apikey: <apikey>',
    'Authorization: Bearer <access-token>'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

## Subscribe Event

## Subscribe an event

<mark style="color:green;">`POST`</mark> `‎https://<domain>/<api prefix>/<version>/webhook/subscribe/`

This API endpoint is used to subscribe to a webhook event. For subscribing to an event minimum of one event slug and an URL is required. Before initiating the validation flow, the system will generate a string that will act as a challenge code.&#x20;

Use this challenge code as a query parameter to make an HTTP POST to your webhook endpoint.&#x20;

eg: [https://webhooks.example.com?challenge\_code](https://webhooks.example.com/linkedin?challengeCode=890e4665-4dfe-4ab1-b689-ed553bceeed0)="\<challange\_code>"

Your application must compute the challenge\_response using the provided encryption file. Return both the challenge\_code and challenge\_response in a JSON payload with a 200 OK status.

challenge\_code - given challenge code through your webhook endpoint as a query param,

challenge\_response - encrypt the challenge code using provided encryption file keys,&#x20;

clientSecret key for encryption is **"webhook",**

eg response (JSON):

**`{"challenge_code`*****`" : "<`*****`challenge_code>", "challenge_response" : "<challenge_response>" }`**

On receiving the validation response, the system will verify by computing the challenge\_response and comparing it with the challenge\_response returned by the app.

If the challenge\_response is successfully verified, then the webhook is ready to be used in subscriptions. If the verification fails, an email will be sent to the admin user, for validating again use the **Webhook Subscriber Validation** endpoint, which is given below. if the validation fails continuously the subscription will be blocked permanently.

An event in the system will post a request to the subscribed URL with a header and payload data. the request header contains a webhook signature which is an encrypted event slug and authorization, to identify the event decrypt the event signature using provided encryption file keys, and the clientSecret Key for event-signature is **"webhook-event"**.

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| apikey<mark style="color:red;">\*</mark>        | string | Apikey              |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Request Body

| Name                                     | Type   | Description                                                                              |
| ---------------------------------------- | ------ | ---------------------------------------------------------------------------------------- |
| events<mark style="color:red;">\*</mark> | array  | <p>An array of event slug</p><p><a data-mention href="#list-events">#list-events</a></p> |
| url<mark style="color:red;">\*</mark>    | string | Endpoint url                                                                             |

{% tabs %}
{% tab title="200: OK " %}

```html
HTTP/1.1 200 OK
Content-Type: application/json
{
    "status_code": 200,
    "errors": {},
    "data": {
        "uuid": "<unique_subscription_id>", //save this uuid for future subscription manage.
        "user": "<admin_user_mail>",
        "events": [
            "<event_slug>", ...
        ],
        "url": "<subscription_endpoint_url>",
        "content_type": "<content_type>",
        "is_broken": <is_broken>,
        "is_verified": <is_verified>,
        "is_disabled": <is_disabled>,
        "is_plugin": <is_plugin>,
        "created": "<created_date>"
    }
}
```

{% endtab %}
{% endtabs %}

#### Sample Code

**Node**

```javascript
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://<domain>/<api prefix>/<version>/webhook/subscribe/',
  'headers': {
    'apikey': '<apikey>',
    'Authorization': 'Bearer <access_token>',
  },
  body: JSON.stringify({"events":["event_slug",..],"url":"<endpoit_url>"})
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

**PHP**

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<domain>/<api prefix>/<version>/webhook/subscribe/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'    {
        "events": ["<event_slug>",...],
        "url": "<endpoint_url>"
    }',
  CURLOPT_HTTPHEADER => array(
    'apikey: <apikey>',
    'Authorization: Bearer <access_token>',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

**Error Responses**

<table><thead><tr><th data-type="number">Status Code</th><th>Error Type</th><th>Field</th><th>Description</th></tr></thead><tbody><tr><td>400</td><td>Validation Error</td><td>events</td><td><p>This field is required.</p><p>This list may not be empty.</p><p>'&#x3C;event-slug>' this webhook event is already subscribed for this API User.</p></td></tr><tr><td>400</td><td>Validation Error</td><td>url</td><td><p>This field is required.</p><p>This field may not be blank.</p><p>Enter a valid URL.</p><p>Protocol of recipient URL not allowed (('https://',) only).</p></td></tr></tbody></table>

## **Webhook Subscriber Validation**

## Webhook Validation

<mark style="color:green;">`POST`</mark> `‎https://<domain>/<api prefix>/<version>/webhook/subscribe/validate/<uuid>/`

This API endpoint is used to validate or verify a non-verified webhook subscription.

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| apikey<mark style="color:red;">\*</mark>        | string | Apikey              |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

{% tabs %}
{% tab title="200: OK " %}

```html
{
    "status_code": 200,
    "errors": {},
    "data": {}
}
```

{% endtab %}
{% endtabs %}

#### **Sample Code**

**Node**

```javascript
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://<domain>/<api prefix>/<version>/webhook/subscribe/validate/<uuid>/',
  'headers': {
    'apikey': '<apikey>',
    'Authorization': 'Bearer <access-token>',
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

**PHP**

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<domain>/<api prefix>/<version>/webhook/subscribe/validate/<uuid>/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => array(
    'apikey: <apikey>',
    'Authorization: Bearer <access-token>',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

#### Error Responses

<table><thead><tr><th data-type="number">Status Code</th><th>Error Type</th><th>Field</th><th>Description</th></tr></thead><tbody><tr><td>400</td><td>Validation Error</td><td>uuid</td><td><p>This subscription is blocked due to maximum validation attempt (&#x3C;max<em>attempt</em>count>), Please contact admin for unblocking your subscription.</p><p></p><p>This subscription is already verified.</p></td></tr><tr><td>404</td><td>Not Found</td><td></td><td>The requested resource not found.</td></tr><tr><td>null</td><td></td><td></td><td></td></tr></tbody></table>

## Update Subscription

## Update a subscription

<mark style="color:green;">`POST`</mark> `‎https://<domain>/<api prefix>/<version>/webhook/update/<uuid>/`

This API endpoint is used to update a webhook event subscription.

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| apikey<mark style="color:red;">\*</mark>        | string | Apikey              |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Request Body

| Name         | Type    | Description       |
| ------------ | ------- | ----------------- |
| url          | sring   | URL               |
| events       | array   | List of events    |
| is\_disabled | boolean | Enable or Disable |

{% tabs %}
{% tab title="200: OK " %}

```html
HTTP/1.1 200 OK
Content-Type: application/json
{
    "status_code": 200,
    "errors": {},
    "data": {
        "uuid": "<unique_subscription_id>", //save this uuid for future subscription manage.
        "user": "<admin_user_mail>",
        "events": [
            "<event_slug>", ...
        ],
        "url": "<subscription_endpoint_url>",
        "content_type": "<content_type>",
        "is_broken": <is_broken>,
        "is_verified": <is_verified>,
        "is_disabled": <is_disabled>,
        "is_plugin": <is_plugin>,
        "created": "<created_date>"
    }
}
```

{% endtab %}
{% endtabs %}

#### **Sample Code**

**Node**

```javascript
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://<domain>/<api prefix>/<version>/webhook/update/<uuid>/',
  'headers': {
    'apikey': '<apikey>',
    'Authorization': 'Bearer <access_token>',
  },
  body: JSON.stringify({"events":["event_slug",..],"url":"<endpoit_url>","is_disabled":<boolean>})
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

**PHP**

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<domain>/<api prefix>/<version>/webhook/update/<uuid>/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'    {
        "events": ["<event_slug>",...],
        "url": "<endpoint_url>",
        "is_disabled":<boolean>
    }',
  CURLOPT_HTTPHEADER => array(
    'apikey: <apikey>',
    'Authorization: Bearer <access_token>',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;p
```

**Note:-** Error Responses are the same as an event subscription.&#x20;

## Webhook Info

## Webhook Info

<mark style="color:blue;">`GET`</mark> `‎https://<domain>/<api prefix>/<version>/webhook/info/<uuid>/`

This API endpoint is used to get webhook subscription details.

#### Headers

| Name                                            | Type                         | Description |
| ----------------------------------------------- | ---------------------------- | ----------- |
| apikey<mark style="color:red;">\*</mark>        | string - Apikey              |             |
| Authorization<mark style="color:red;">\*</mark> | string - Bearer access token |             |

{% tabs %}
{% tab title="200: OK " %}

```javascript
HTTP/1.1 200 OK
Content-Type: application/json
{
    "status_code": 200,
    "errors": {},
    "data": {
        "uuid": "<unique_subscription_id>", //save this uuid for future subscription manage.
        "user": "<admin_user_mail>",
        "events": [
            "<event_slug>", ...
        ],
        "url": "<subscription_endpoint_url>",
        "content_type": "<content_type>",
        "is_broken": <is_broken>,
        "is_verified": <is_verified>,
        "is_disabled": <is_disabled>,
        "is_plugin": <is_plugin>,
        "created": "<created_date>"
    }
}
```

{% endtab %}
{% endtabs %}

#### Sample Code

**Node**

```javascript
var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://<domain>/<api prefix>/<version>/webhook/info/<uuid>/',
  'headers': {
    'apikey': '<apikey>',
    'Authorization': 'Bearer <access-token>',
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

**PHP**

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<domain>/<api prefix>/<version>/webhook/info/<uuid>/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'apikey: <apikey>',
    'Authorization: Bearer <access-token>',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

```

## Unsubscribe Event

## Unsubscribe webhook event

<mark style="color:red;">`DELETE`</mark> `‎https://<domain>/<api prefix>/<version>/webhook/unsubscribe/<uuid>/`

This API endpoint is used to unsubscribe or delete an event subscription.

#### Headers

| Name                                           | Type                         | Description |
| ---------------------------------------------- | ---------------------------- | ----------- |
| apikey<mark style="color:red;">\*</mark>       | string - Apikey              |             |
| Authorizaion<mark style="color:red;">\*</mark> | string - Bearer access-token |             |

{% tabs %}
{% tab title="200: OK " %}

```html
{
    "status_code": 200,
    "errors": {},
    "data": {}
}
```

{% endtab %}
{% endtabs %}

#### **Sample Code**

**Node**

```javascript
var request = require('request');
var options = {
  'method': 'DELETE',
  'url': 'https://<domain>/<api prefix>/<version>/webhook/unsubscribe/<uuid>/',
  'headers': {
    'apikey': '<apikey>',
    'Authorization': 'Bearer <access token>',
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

```

**PHP**

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<domain>/<api prefix>/<version>/webhook/unsubscribe/<uuid>/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_HTTPHEADER => array(
    'apikey: <apikey>',
    'Authorization: Bearer <access-token>',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

## List Subscriptions

## List event subscriptions

<mark style="color:blue;">`GET`</mark> `‎https://<domain>/<api prefix>/<version>/webhook/list/`

This API endpoint is used to list webhook event subscriptions.

#### Headers

| Name                                            | Type                         | Description |
| ----------------------------------------------- | ---------------------------- | ----------- |
| apikey<mark style="color:red;">\*</mark>        | string - Apikey              |             |
| Authorization<mark style="color:red;">\*</mark> | string - Bearer access token |             |

{% tabs %}
{% tab title="200: OK " %}

```html
{
    "status_code": 200,
    "errors": {},
    "data": {
        "results": [
            {
                 "uuid": "<unique_subscription_id>",
                 "user": "<admin_user_mail>",
                 "events": [
                    "<event_slug>", ...
                 ],
                 "url": "<subscription_endpoint_url>",
                 "content_type": "<content_type>",
                 "is_broken": <is_broken>,
                 "is_verified": <is_verified>,
                 "is_disabled": <is_disabled>,
                 "is_plugin": <is_plugin>,
                 "created": "<created_date>"
           },
           ...
        ],
        "count": <list_count>,
        "previous": <previous_page_url>,
        "next": <next_page_url>
    }
}
```

{% endtab %}
{% endtabs %}

#### Sample Code

**Node**

```javascript
var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://<domain>/<api prefix>/<version>/webhook/list/',
  'headers': {
    'apikey': '<apikey>',
    'Authorization': 'Bearer <access token>',
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

**PHP**

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<domain>/<api prefix>/<version>/webhook/list/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'apikey: <apikey>',
    'Authorization: Bearer <access token>',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

## Provided Webhook Events

These are available webhook events in the system and the data given by the event.

{% tabs %}
{% tab title="Event Name" %}
**User Registration**
{% endtab %}

{% tab title="Event Slug" %}
**user-registration**
{% endtab %}

{% tab title="Data (JSON)" %}

```html
{
    'email': '<user_email_address>', 
    'sponsor': '<sponsor_user_name>', 
    'username': '<username>', 
    'is_active': <user_status>, 
    'last_name': '<last_name>', 
    'unique_id': '<unique_id>', 
    'user_role': 
        [
            {
                'name': '<user_role_name>'
            }
        ], 
    'first_name': '<first_name>', 
    'phone_code': <phone_code>, 
    'phone_number': '<phone_number>'
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Event Name" %}
**Order Creation**
{% endtab %}

{% tab title="Event Slug" %}
**order-creation**
{% endtab %}

{% tab title="Data (JSON)" %}
if the order type is **Commerce,**

```html
{
    'uid': '<user_unique_id>', 
    'status': '<order_status>', 
    'products': [
        {
            'bv': <bv>, 
            'cv': <cv>, 
            'point': <points> 
            'total': <product_total_price>, 
            'quantity': <quantity>, 
            'product_name': '<product_name>', 
            'product_base_price': '<product_base_price>',
            'product_id': '<product_id>'
        },
        ...
    ], 
    'username': '<username>', 
    'last_name': '<last_name>', 
    'first_name': '<first_name>', 
    'order_type': '<order_type>', 
    'order_total': '<order_total>', 
    'currency_code': '<currency_code>',
    'order_number': '<order_number>'
}
```

if the order type is **Enrollment,**

```html
{
    'bv': '<bv>', 
    'cv': '<cv>', 
    'uid': '<user_unique_id>', 
    'points': '<points>', 
    'status': '<order_status>', 
    'username': '<username>', 
    'last_name': '<last_name>', 
    'first_name': '<first_name>', 
    'order_type': 'ENROLLMENT', 
    'product_id': '<product_id>', 
    'amount_paid': '<amount_paid>', 
    'order_total': '<order_total>', 
    'product_name': '<product_name>', 
    'actual_amount': '<actual_amount>', 
    'currency_code': '<currency_code>', 
    'payment_status': '<payment_status>', 
    'product_base_price': '<product_base_price>',
    'order_number': '<order_number>'
}	
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Event Name" %}
**Block User**
{% endtab %}

{% tab title="Event Slug" %}
**block-user**
{% endtab %}

{% tab title="Data (JSON)" %}

```html
[
    {'unique_id': '<blocked_user_unique_id>'},
    ...
]
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Event Name" %}
**Unblock User**
{% endtab %}

{% tab title="Event Slug" %}
**unblock-user**
{% endtab %}

{% tab title="Data (JSON)" %}

```html
[
    {'unique_id': '<blocked_user_unique_id>'},
    ...
]
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Event Name" %}
**Product Creation**
{% endtab %}

{% tab title="Event Slug" %}
**product-creation**
{% endtab %}

{% tab title="Data (JSON)" %}

```html
{
    'bundle_id': '<bundle_id>'
}	
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Event Name" %}
**Product Update**
{% endtab %}

{% tab title="Event Slug" %}
**product-update**
{% endtab %}

{% tab title="Data (JSON)" %}

```html
{
    'bundle_id': '<bundle_id>'
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Event Name" %}
**Product Delete**
{% endtab %}

{% tab title="Event Slug" %}
**product-delete**
{% endtab %}

{% tab title="Data (JSON)" %}

```html
{
    'bundle_id': '<bundle_id>'
}	
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Event Name" %}
**Profile Update**
{% endtab %}

{% tab title="Event Slug" %}
**profile-update**
{% endtab %}

{% tab title="Data (JSON)" %}

```html
{
    'unique_id': '<unique_id>'
}	
```

{% endtab %}
{% endtabs %}