> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipstream.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/merchant-api/webhook-topics) and specifies a URL which event data will be sent via HTTP POST as events occur. See the [Topics](/merchant-api/webhook-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 title="PHP Example" theme={null}
$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](#webhook-list)
* [webhook.create](#webhook-create)
* [webhook.update\_status](#webhookupdate-status)
* [webhook.delete](#webhook-delete)
***
## Entity Properties
* [Webhook](#webhook-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
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"webhook.list",
[]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"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](/merchant-api/webhook-topics).
### Parameters
Webhook data.
### Return Value
`true` if webhook was successfully created.
### Example Request
```json title="Request" theme={null}
{
"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
```json title="Response" theme={null}
{
"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
Topic
Status. Allowed values: "0" - inactive or "1" - active.
### Return Value
`true` if status was successfully updated.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"webhook.update_status",
[
{
"status" : 1
}
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"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
Webhook Id.
### Return Value
`true` if webhook was successfully deleted.
### Example Request
```json title="Request" theme={null}
{
"jsonrpc" : 2.0,
"id" : 1234,
"method" : "call",
"params" : [
"be1c13ed4e03f0ed7f1e4053dfff9658",
"webhook.delete",
[
123
]
]
}
```
### Example Response
```json title="Response" theme={null}
{
"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
The internal webhook ID.
Sequential ID of each payload so missed events can be detected easily.
Flag to determine whether the webhook is active. Allowed values: "0" - inactive or "1" - active.
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.
Either a string with one or more topics separated by commas or an array of topics which the webhook is subscribed to.
Url for the webhook callback.
Extra headers.
Secret Key is used for the webhook signature.