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

​
Entity Properties

​
webhook.list

webhook.list() Retrieve webhooks list.

​
Parameters

The method is used without parameters.

​
Return Value

An array of objects with webhook information.

​
Example Request

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

​
Example Response

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

webhook.create(object $webhookData) Create new webhook for a single or multiple topics.

​
Parameters

​
webhookData
object
Webhook data.

​
Return Value

true if webhook was successfully created.

​
Example Request

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

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

​
Error Codes

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

​
webhook.update_status

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

​
Parameters

​
topic
string
Topic
​
status
number
Status. Allowed values: “0” - inactive or “1” - active.

​
Return Value

true if status was successfully updated.

​
Example Request

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

​
Example Response

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

​
Error Codes

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

​
webhook.delete

webhook.delete(int $webhookId) Delete webhook.

​
Parameters

​
webhookId
integer
Webhook Id.

​
Return Value

true if webhook was successfully deleted.

​
Example Request

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

​
Example Response

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

​
Error Codes

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

​
Entity Properties

​
Webhook Properties

​
webhook_id
integer
The internal webhook ID.
​
increment_id
integer
Sequential ID of each payload so missed events can be detected easily.
​
is_active
integer
Flag to determine whether the webhook is active. Allowed values: “0” - inactive or “1” - active.
​
topics
string | array
Either a string with one or more topics separated by commas or an array of topics which the webhook is subscribed to.
​
url
string
Url for the webhook callback.
​
extra_headers
string
Extra headers.
​
secret_key
string
Secret Key is used for the webhook signature.