Webhook

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

Entity Properties

Webhook

`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,
            "include_pcd" : 0,
            "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

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,
                "include_pcd" : 0,
                "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

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`

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

Parameters

string

Topic

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

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

`webhook.delete`

webhook.delete(int $webhookId) Delete webhook.

Parameters

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

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

Entity Properties

Webhook Properties

integer

The internal webhook ID.

integer

Sequential ID of each payload so missed events can be detected easily.

integer

Flag to determine whether the webhook is active. Allowed values: “0” - inactive or “1” - active.

integer

Flag to determine whether Protected Customer Data (PCD) — such as the shipping address and contact info — is populated in the webhook payload. Allowed values: “0” - excluded (default) or “1” - included.

string | array

Either a string with one or more topics separated by commas or an array of topics which the webhook is subscribed to.

string

Url for the webhook callback.

string

Extra headers.

string

Secret Key is used for the webhook signature.

Get Started

Common Features

Shipping

Receiving

Inventory

System

Authentication

Webhook Retry Intervals

Methods

Entity Properties

`webhook.list`

Parameters

Return Value

Example Request

Example Response

`webhook.create`

Parameters

Return Value

Example Request

Example Response

Error Codes

`webhook.update_status`

Parameters

Return Value

Example Request

Example Response

Error Codes

`webhook.delete`

Parameters

Return Value

Example Request

Example Response

Error Codes

Entity Properties

Webhook Properties

​Authentication

​Webhook Retry Intervals

​Methods

​Entity Properties

​webhook.list

​Parameters

​Return Value

​Example Request

​Example Response

​webhook.create

​Parameters

​Return Value

​Example Request

​Example Response

​Error Codes

​webhook.update_status

​Parameters

​Return Value

​Example Request

​Example Response

​Error Codes

​webhook.delete

​Parameters

​Return Value

​Example Request

​Example Response

​Error Codes

​Entity Properties

​Webhook Properties

Authentication

Webhook Retry Intervals

Methods

Entity Properties

`webhook.list`

Parameters

Return Value

Example Request

Example Response

`webhook.create`

Parameters

Return Value

Example Request

Example Response

Error Codes

`webhook.update_status`

Parameters

Return Value

Example Request

Example Response

Error Codes

`webhook.delete`

Parameters

Return Value

Example Request

Example Response

Error Codes

Entity Properties

Webhook Properties