1. Threekit
  2. Developer Documentation
  3. Connecting and Displaying Externally (APIs)
  4. APIs

Webhooks API

In this article

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.

  1. id - Webhook ID
  2. address - Address notified when the webhook is triggered
  3. topic - The condition which causes a webhook to trigger
  4. orgId - Organization ID
  5. createdBy - ID of the user who created the webhook
  6. createdAt - The time when the webhook was created
  7. updatedAt - The time when the webhook was updated last time
  8. 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.

  1. id - Webhook ID
  2. address - Address notified when the webhook is triggered
  3. topic - The condition which causes a webhook to trigger
  4. orgId - Organization ID
  5. createdBy - ID of the user who created the webhook
  6. createdAt - The time when the webhook was created
  7. updatedAt - The time when the webhook was updated last time
  8. 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
Was this article helpful? Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles

Powered by Zendesk