Webhook

Webhook Management

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

GET ‎https://<domain>/<api prefix>/<version>/webhook/list/events/

This API endpoint provided a list of available webhook events.

Headers

Name	Type	Description
apikey*	string	Apikey
Authorization*	string	Bearer access token

200: OK

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>
    }
}

Sample Code

Node

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

$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

POST ‎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.

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

eg: https://webhooks.example.com?challenge_code="<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,

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*	string	Apikey
Authorization*	string	Bearer access token

Request Body

Name	Type	Description
events*	array	An array of event slug List Events
url*	string	Endpoint url

200: OK

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>"
    }
}

Sample Code

Node

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

$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

Status Code	Error Type	Field	Description
400	Validation Error	events	This field is required. This list may not be empty. '<event-slug>' this webhook event is already subscribed for this API User.
400	Validation Error	url	This field is required. This field may not be blank. Enter a valid URL. Protocol of recipient URL not allowed (('https://',) only).

Webhook Subscriber Validation

Webhook Validation

POST ‎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*	string	Apikey
Authorization*	string	Bearer access token

200: OK

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

Sample Code

Node

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

$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

Status Code	Error Type	Field	Description
400	Validation Error	uuid	This subscription is blocked due to maximum validation attempt (<maxattemptcount>), Please contact admin for unblocking your subscription. This subscription is already verified.
404	Not Found		The requested resource not found.
null

Update Subscription

Update a subscription

POST ‎https://<domain>/<api prefix>/<version>/webhook/update/<uuid>/

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

Headers

Name	Type	Description
apikey*	string	Apikey
Authorization*	string	Bearer access token

Request Body

Name	Type	Description
url	sring	URL
events	array	List of events
is_disabled	boolean	Enable or Disable

200: OK

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>"
    }
}

Sample Code

Node

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

$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.

Webhook Info

Webhook Info

GET ‎https://<domain>/<api prefix>/<version>/webhook/info/<uuid>/

This API endpoint is used to get webhook subscription details.

Headers

Name	Type	Description
apikey*	string - Apikey
Authorization*	string - Bearer access token

200: OK

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>"
    }
}

Sample Code

Node

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

$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

DELETE ‎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*	string - Apikey
Authorizaion*	string - Bearer access-token

200: OK

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

Sample Code

Node

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

$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

GET ‎https://<domain>/<api prefix>/<version>/webhook/list/

This API endpoint is used to list webhook event subscriptions.

Headers

Name	Type	Description
apikey*	string - Apikey
Authorization*	string - Bearer access token

200: OK

{
    "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>
    }
}

Sample Code

Node

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

$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.

Event Name

User Registration

Event Slug

user-registration

Data (JSON)

{
    '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>'
}

Event Name

Order Creation

Event Slug

order-creation

Data (JSON)

if the order type is Commerce,

{
    '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,

{
    '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>'
}	

Event Name

Block User

Event Slug

block-user

Data (JSON)

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

Event Name

Unblock User

Event Slug

unblock-user

Data (JSON)

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

Event Name

Product Creation

Event Slug

product-creation

Data (JSON)

{
    'bundle_id': '<bundle_id>'
}	

Event Name

Product Update

Event Slug

product-update

Data (JSON)

{
    'bundle_id': '<bundle_id>'
}

Event Name

Product Delete

Event Slug

product-delete

Data (JSON)

{
    'bundle_id': '<bundle_id>'
}	

Event Name

Profile Update

Event Slug

profile-update

Data (JSON)

{
    'unique_id': '<unique_id>'
}