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

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;

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

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

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

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

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

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

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

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

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

User Registration

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

Order Creation

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

Block User

Unblock User

Product Creation

Product Update

Product Delete

Profile Update

PreviousSaved Cards

Last updated 4 years ago

Was this helpful?

hashtagIntroduction

hashtagList Events

hashtagList Provided Webhook Events

hashtagHeaders

hashtagSample Code

hashtagSubscribe Event

hashtagSubscribe an event

hashtagHeaders

hashtagRequest Body

hashtagSample Code

hashtagWebhook Subscriber Validation

hashtagWebhook Validation

hashtagHeaders

hashtagSample Code

hashtagError Responses

hashtagUpdate Subscription

hashtagUpdate a subscription

hashtagHeaders

hashtagRequest Body

hashtagSample Code

hashtagWebhook Info

hashtagWebhook Info

hashtagHeaders

hashtagSample Code

hashtagUnsubscribe Event

hashtagUnsubscribe webhook event

hashtagHeaders

hashtagSample Code

hashtagList Subscriptions

hashtagList event subscriptions

hashtagHeaders

hashtagSample Code

hashtagProvided Webhook Events

Introduction

List Events

List Provided Webhook Events

Headers

Sample Code

Subscribe Event

Subscribe an event

Headers

Request Body

Sample Code

Webhook Subscriber Validation

Webhook Validation

Headers

Sample Code

Error Responses

Update Subscription

Update a subscription

Headers

Request Body

Sample Code

Webhook Info

Webhook Info

Headers

Sample Code

Unsubscribe Event

Unsubscribe webhook event

Headers

Sample Code

List Subscriptions

List event subscriptions

Headers

Sample Code

Provided Webhook Events