Webhook

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

Webhook Retry Intervals

Webhook retries occur for any non-20X response. There is a 3-second connect timeout and a 5-second overall timeout. ShipStream will make up to 14 retires. Each failed retry will be delayed. Instead of making the 15th attempt, ShipStream will mark the queued webhook call with the status “failed”.

Retry Intervals:

  • +1 minute
  • +2 minutes
  • +4 minutes
  • +8 minutes
  • +15 minutes
  • +30 minutes
  • +1 hour
  • +2 hours
  • +4 hours
  • +8 hours
  • +16 hours
  • +24 hours
  • +24 hours
  • +24 hours

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:created",
            "url" : "http://example.com",
            "extra_headers" : "",
            "secret_key" : "2RUJ8NXLnLRrAj3"
        }
    ]
}

webhook.create (object $webhookData)

Create new webhook for a single or multiple topics.

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:created","order:canceled"],
                "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

f
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" }
{ "topics" : "order:created,order:canceled" }
{ "topics" : ["order:created","order:canceled"] }
Either a string with one or more topics separated by commas or an array of topics which 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.