Webhooks API

GET https://admin.threekit.com/api/webhooks

Retrieves the list of webhooks by topic or address if passed. The list will contain all webhooks from the token's organization. For each entry the following information will be available.

id - Webhook ID
address - Address notified when the webhook is triggered
topic - The condition which causes a webhook to trigger
orgId - Organization ID
createdBy - ID of the user who created the webhook
createdAt - The time when the webhook was created
updatedAt - The time when the webhook was updated last time
deletedAt - The time when the webhook was deleted (If present)

REST Endpoint

GET https://admin.threekit.com/api/webhooks?bearer_token=[bearer_token]&orgId=[orgId]&topic=[topic]&address=[address]

Query Parameters

Name	In	Type	Required	Description
bearer_token	query	string	false	Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token.
orgId	query	string	false	Organization ID.
topic	query	string	false	Topic of a webhook
address	query	string	false	Address of a webhook

Response Codes

Status	Meaning	Description	Schema
200	OK	Successful get request, response body will include the list of webhooks	None
401	Unauthorized	User is not authenticated. They must be authenticated to use this service.	None
403	Forbidden	No token was provided in the query string of the request	None

Example Implementations

Code

CURL

curl --request GET \
  --url https://admin.threekit.com/api/webhooks \
  --header 'authorization: Bearer {access-token}'

Node.JS

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "admin.threekit.com",
  "port": null,
  "path": "/api/webhooks",
  "headers": {
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://admin.threekit.com/api/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer {access-token}"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Example responses

{
  "webhooks": [
    {
      "id": "5cf78a4d-bf30-4e6b-a7bd-fcbffeb04e97",
      "orgId": "2ea6ad9d-04e1-49e3-bc45-aaacd74274d6",
      "createdBy": "26faa06a-a8e9-4d64-96fa-ce6f86cdc60b",
      "topic": "orders.created",
      "address": "https://example.com",
      "createdAt": "2020-03-16T16:10:29.785Z",
      "updatedAt": "2020-03-16T16:10:29.785Z",
      "deletedAt": null
    },
    {
      "id": "7d787c32-8cbc-4d1e-ad4e-465adfd9198f",
      "orgId": "2ea6ad9d-04e1-49e3-bc45-aaacd74274d6",
      "createdBy": "f616c9e1-2a99-447c-b5c9-5b61b462a274",
      "topic": "orders.created",
      "address": "https://example.com",
      "createdAt": "2020-03-13T20:13:58.796Z",
      "updatedAt": "2020-03-13T20:13:58.796Z",
      "deletedAt": null
    }
  ]
}

{
  "error": {
    "code": "users_service_unavailable",
    "message": "Error reaching users service"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "forbidden"
  }
}

POST https://admin.threekit.com/api/webhooks

Creates a webhook which sends a POST request to the provided address when the provided topic occurs. The sent request body will include the webhook's ID, the topic which occurred, and any relevant information about that topic.

REST Endpoint

POST https://admin.threekit.com/api/webhooks?bearer_token=[bearer_token]

Query Parameters

Name	In	Type	Required	Description
bearer_token	query	string	false	Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token.

Body Parameters

false

Response Codes

Status	Meaning	Description	Schema
200	OK	Successful post request, response body will include the created webhook details.	None
401	Unauthorized	User is not authenticated. They must be authenticated to use this service.	None
403	Forbidden	No token was provided in the query string of the request	None

Example Implementations

Code

CURL

curl --request POST \
  --url https://admin.threekit.com/api/webhooks \
  --header 'authorization: Bearer {access-token}' \
  --header 'content-type: application/json' \
  --data false

Node.JS

var http = require("https");

var options = {
  "method": "POST",
  "hostname": "admin.threekit.com",
  "port": null,
  "path": "/api/webhooks",
  "headers": {
    "content-type": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://admin.threekit.com/api/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "false",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer {access-token}",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Example responses

[
  {
    "address": "https://example.com",
    "createdAt": "2020-03-17T15:03:39.852Z",
    "createdBy": "c84c4754-1f25-4a5a-9e24-2ba870c12bfd",
    "deletedAt": "1970-01-01T00:00:00.000Z",
    "id": "2528341b-4d5a-4fb8-aa0c-cf3b6f60ec49",
    "orgId": "181c00e0-ad2c-4446-bca2-e39f4aade452",
    "topic": "orders.created",
    "updatedAt": "2020-03-17T15:03:39.852Z"
  }
]

{
  "error": {
    "code": "users_service_unavailable",
    "message": "Error reaching users service"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "forbidden"
  }
}

GET https://admin.threekit.com/api/webhooks/{id}

Retrieves a webhook. The webhook will have the following information available.

id - Webhook ID
address - Address notified when the webhook is triggered
topic - The condition which causes a webhook to trigger
orgId - Organization ID
createdBy - ID of the user who created the webhook
createdAt - The time when the webhook was created
updatedAt - The time when the webhook was updated last time
deletedAt - The time when the webhook was deleted (If present)

REST Endpoint

GET https://admin.threekit.com/api/webhooks/{id}?bearer_token=[bearer_token]&orgId=[orgId]

Query Parameters

Name	In	Type	Required	Description
id	path	string	true	ID of the webhook to be retrieved.
bearer_token	query	string	false	Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token.
orgId	query	string	false	Organization ID.

Response Codes

Status	Meaning	Description	Schema
200	OK	Returns a webhook's information	None
401	Unauthorized	User is not authenticated. They must be authenticated to use this service.	None
403	Forbidden	No token was provided in the query string of the request	None
404	Not Found	No webhook was found for the given ID	None

Example Implementations

Code

CURL

curl --request GET \
  --url https://admin.threekit.com/api/webhooks/string \
  --header 'authorization: Bearer {access-token}'

Node.JS

var http = require("https");

var options = {
  "method": "GET",
  "hostname": "admin.threekit.com",
  "port": null,
  "path": "/api/webhooks/string",
  "headers": {
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://admin.threekit.com/api/webhooks/string",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer {access-token}"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Example responses

[
  {
    "address": "https://example.com",
    "createdAt": "2020-03-17T15:03:39.852Z",
    "createdBy": "5a0a52c1-5e92-4643-b28a-57e94c1322da",
    "deletedAt": "1970-01-01T00:00:00.000Z",
    "id": "c96ef151-fed0-4bc5-8a3c-62c91173dbde",
    "orgId": "92e43401-0824-43b7-9513-605a845a2a26",
    "topic": "orders.created",
    "updatedAt": "2020-03-17T15:03:39.852Z"
  }
]

{
  "error": {
    "code": "users_service_unavailable",
    "message": "Error reaching users service"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "forbidden"
  }
}

{
  "error": {
    "code": "webhook_not_found",
    "message": "Webhook not found"
  }
}

PUT https://admin.threekit.com/api/webhooks/{id}

Modifies a webhook.

REST Endpoint

PUT https://admin.threekit.com/api/webhooks/{id}?bearer_token=[bearer_token]

Query Parameters

Name	In	Type	Required	Description
id	path	string	true	ID of the webhook to be modified.
bearer_token	query	string	false	Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token.

Body Parameters

false

Response Codes

Status	Meaning	Description	Schema
200	OK	Returns a modified webhook's information	None
401	Unauthorized	User is not authenticated. They must be authenticated to use this service.	None
403	Forbidden	No token was provided in the query string of the request	None
404	Not Found	No webhook was found for the given ID	None

Example Implementations

Code

CURL

curl --request PUT \
  --url https://admin.threekit.com/api/webhooks/string \
  --header 'authorization: Bearer {access-token}' \
  --header 'content-type: application/json' \
  --data false

Node.JS

var http = require("https");

var options = {
  "method": "PUT",
  "hostname": "admin.threekit.com",
  "port": null,
  "path": "/api/webhooks/string",
  "headers": {
    "content-type": "application/json",
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://admin.threekit.com/api/webhooks/string",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "false",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer {access-token}",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Example responses

[
  {
    "address": "https://example.com",
    "createdAt": "2020-03-17T15:03:39.852Z",
    "createdBy": "72208d2a-97fe-4d04-a2cd-94dbc210d4e8",
    "deletedAt": "1970-01-01T00:00:00.000Z",
    "id": "8e41cb8f-c405-478a-8a7d-cddf46a4bdd9",
    "orgId": "4ca40fc7-8d0d-4b17-b5b9-4a79bf9c8fc6",
    "topic": "orders.created",
    "updatedAt": "2020-03-17T15:26:51.590Z"
  }
]

{
  "error": {
    "code": "users_service_unavailable",
    "message": "Error reaching users service"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "forbidden"
  }
}

{
  "error": {
    "code": "webhook_not_found",
    "message": "Webhook not found"
  }
}

DELETE https://admin.threekit.com/api/webhooks/{id}

Deletes a webhook.

REST Endpoint

DELETE https://admin.threekit.com/api/webhooks/{id}?bearer_token=[bearer_token]&orgId=[orgId]

Query Parameters

Name	In	Type	Required	Description
id	path	string	true	ID of the webhook to be deleted.
bearer_token	query	string	false	Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token.
orgId	query	string	false	Organization ID.

Response Codes

Status	Meaning	Description	Schema
200	OK	Deletes a webhook	None
401	Unauthorized	User is not authenticated. They must be authenticated to use this service.	None
403	Forbidden	No token was provided in the query string of the request	None
404	Not Found	No webhook was found for the given ID	None

Example Implementations

Code

CURL

curl --request DELETE \
  --url https://admin.threekit.com/api/webhooks/string \
  --header 'authorization: Bearer {access-token}'

Node.JS

var http = require("https");

var options = {
  "method": "DELETE",
  "hostname": "admin.threekit.com",
  "port": null,
  "path": "/api/webhooks/string",
  "headers": {
    "authorization": "Bearer {access-token}"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://admin.threekit.com/api/webhooks/string",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer {access-token}"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Example responses

[
  {
    "address": "https://example.com",
    "createdAt": "2020-03-17T16:04:03.438Z",
    "createdBy": "8cce2483-edd9-417c-9fb7-8dcafcf22cf5",
    "deletedAt": "2020-03-17T16:04:08.162Z",
    "id": "2903207d-5315-45f9-b294-7fe0609d43af",
    "orgId": "9c6b3de5-7409-4775-b7e5-aa71acad0f72",
    "topic": "orders.created",
    "updatedAt": "2020-03-17T16:04:08.162Z"
  }
]

{
  "error": {
    "code": "users_service_unavailable",
    "message": "Error reaching users service"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "forbidden"
  }
}

{
  "error": {
    "code": "webhook_not_found",
    "message": "Webhook not found"
  }
}

Schemas

create webhook body

{
  "topic": "string",
  "address": "string",
  "orgId": "string"
}

Properties

Name	Type	Required	Restrictions	Description
topic	string	false	none	Topic of the webhook to be created.
address	string	false	none	Address of the webhook to be created.
orgId	string	false	none	Organization which owns the webhook.

update webhook body

{
  "topic": "string",
  "address": "string"
}

Properties

Name	Type	Required	Restrictions	Description
topic	string	false	none	Topic of the webhook to be created.
address	string	false	none	Address of the webhook to be created.

webhook trigger payload

{
  "topic": "string",
  "data": {},
  "webhook": {}
}

the request body that is sent to the webhook urls when a webhook is triggered

Properties

Name	Type	Required	Restrictions	Description
topic	string	false	none	Topic of the webhook
data	object	false	none	Payload object. (order, job, etc).
webhook	object	false	none	the webhook object

Menu

In this article

GET https://admin.threekit.com/api/webhooks

REST Endpoint

Query Parameters

Response Codes

Example Implementations

Code

CURL

Node.JS

PHP

Example responses

POST https://admin.threekit.com/api/webhooks

REST Endpoint

Query Parameters

Body Parameters

Response Codes

Example Implementations

Code

CURL

Node.JS

PHP

Example responses

GET https://admin.threekit.com/api/webhooks/{id}

REST Endpoint

Query Parameters

Response Codes

Example Implementations

Code

CURL

Node.JS

PHP

Example responses

PUT https://admin.threekit.com/api/webhooks/{id}

REST Endpoint

Query Parameters

Body Parameters

Response Codes

Example Implementations

Code

CURL

Node.JS

PHP

Example responses

DELETE https://admin.threekit.com/api/webhooks/{id}

REST Endpoint

Query Parameters

Response Codes

Example Implementations

Code

CURL

Node.JS

PHP

Example responses

Schemas

create webhook body

Properties

update webhook body

Properties

webhook trigger payload

Properties

Related articles