Methods


Entity Properties


Use this API endpoint to register “webhooks” for various events such as when an order has completed or an inventory adjustment is made. A “webhook” subscribes to one or more “topics” and specifies a URL which event data will be sent via HTTP POST as events occur. See the Topics page for details on the available topics and the event details included.

Authentication

Webhook authenticity can be verified by the X-Plugin-Hmac-Sha256 HTTP header which is included with every webhook request. You can compare this header value with the HMAC generated locally to ensure that the request was not spoofed or modified in transit. The HMAC “message” is the entire request body and the HMAC “secret” is the secret_key associated with the webhook.

PHP Example:

$json = file_get_contents('php://input');
$headerValue = $_SERVER['HTTP_X_PLUGIN_HMAC_SHA256'];
$expectedValue = base64_encode(hash_hmac('sha256', $json, $webhookSecretKey, TRUE));
if ($headerValue !== $expectedValue) {
    http_response_code(401);
    exit;
}

Methods

webhook.list ()

Retrieve webhooks list.

Parameters

The method is used without parameters.

Return Value

An array of objects with webhook information.

Example Request

Retrieve webhooks information:

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "webhook.list",
        []
    ]
}

Example Response

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : [
        {
            "webhook_id" : 1,
            "is_active" : 1,
            "topics" : "order:*",
            "url" : "http://example.com",
            "extra_headers" : "",
            "secret_key" : "2RUJ8NXLnLRrAj3"
        }
    ]
}

webhook.create (object $webhookData)

Create new webhook for a single or multiple topics. Multiple topics must be separated by a comma. A prefix pattern-matching syntax is allowed. Example: “order:*”, exact match: “order:created”.

Parameters

orderdescription
1 object - Webhook data.

Return Value

true if webhook was successfully created.

Example Request

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "webhook.create",
        [
            {
                "is_active" : 1,
                "topics" : "order:*",
                "url" : "http://example.com",
                "extra_headers" : "",
                "secret_key" : "2RUJ8NXLnLRrAj3"
            }
        ]
    ]
}

Example Response

{
    "jsonrpc" : 2.0,
    "error" : null,
    "result" : true
}

Error Codes

code message
101 Invalid data given. Details in error message.
102 An unexpected error occurred while creating the webhook.
106 Webhook not created. Details in error message.

webhook.update_status (string $topic, number $status)

Update webhook status.

Parameters

orderdescription
1 string - Topic
2 number - Status. Allowed values: "0" - inactive or "1" - active.

Return Value

true if status was successfully updated.

Example Request

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "webhook.update_status",
        [
            {
                "status" : 1
            }
        ]
    ]
}

Example Response

{
    "jsonrpc" : 2.0,
    "error" : null,
    "result" : true
}

Error Codes

code message
100 Error changing status for specified webhook. Details in error message.

webhook.delete (int $webhookId)

Delete webhook.

Parameters

orderdescription
1 int - Webhook Id.

Return Value

true if webhook was successfully deleted.

Example Request

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "webhook.delete",
        [
            123
        ]
    ]
}

Example Response

{
    "jsonrpc" : 2.0,
    "error" : null,
    "result" : true
}

Error Codes

code message
103 Webhook not exists.
104 An unexpected error occurred while deleting the webhook.
105 Webhook not deleted. Details in error message.

Webhook Properties

webhook_id
{ "webhook_id" : 1 }
The internal webhook ID.
increment_id
{ "increment_id" : 1 }
Sequential ID of each payload so missed events can be detected easily.
is_active
{ "is_active" : 1 }
Flag to determine whether the webhook is active. Allowed values: "0" - inactive or "1" - active.
topics
{ "topics" : "order:created" }
List of topics the webhook is subscribed to.
url
{ "url" : "http://example.com" }
Url for the webhook callback.
extra_headers
{ "extra_headers" : "" }
Extra headers.
secret_key
{ "secret_key" : "2RUJ8NXLnLRrAj3" }
Secret Key is used for the webhook signature.