> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.shipbob.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.shipbob.com/_mcp/server.

# Create Subscription


POST https://api.shipbob.com/2026-01/webhook
Content-Type: application/json

This endpoint creates a new webhook subscription.


Reference: https://developer.shipbob.com/2026-01/api/webhooks/create-subscription

## Authentication

- `Authorization` header (bearer token, required) — Authentication using Personal Access Token (PAT) token
- `Authorization` header (bearer token, required) — OAuth2 authentication using JWT tokens

## Servers

- `https://api.shipbob.com` (https://api.shipbob.com, default)
- `https://sandbox-api.shipbob.com` (https://sandbox-api.shipbob.com)

## Request

### Body (application/json)

This endpoint expects an object.

- `topics` (list of enum, required) — The event types for which webhook callbacks will be received.
  - Allowed values: `order.shipped`, `order.delivered`, `order.shipment.delivered`, `order.shipment.exception`, `order.shipment.on_hold`, `order.shipment.cancelled`, `order.shipment.tracking.updated`, `order.shipment.address.updated`, `order.shipment.line_item.added`, `order.shipment.line_item.removed`, `order.shipment.line_item.updated`, `order.shipment.shipping_service.updated`, `return.created`, `return.updated`, `return.completed`, `return.load_shipment.departed`, `return.gaylord.departed`, `return.load_shipment.arrived`, `return.gaylord.arrived`, `return.gaylord.stow_completed`, `billing.charge.created`, `billing.refund.created`, `billing.credit.created`, `wro.box.arrived`, `wro.box.scanned`, `wro.box.stowed`, `wro.completed`, `wro.created`, `wro.updated`
- `url` (string, required) — The URL that will be called when an event matching the subscription topic occurs. The URL must use HTTPS, accept POST requests, and handle content of type application/json.
- `description` (string, optional, nullable) — Description of the webhook subscription.
- `secret` (string, optional, nullable) — A secret key used to sign the webhook payload for verifying its authenticity on the receiver's end.

## Response

### 200

Success

- `created_at` (datetime, optional) — TimeStamp the webhook subscription was created
- `description` (string, optional, nullable) — Description of the webhook subscription
- `id` (string, optional) — ID of the webhook subscription
- `secret` (string, optional) — A secret key used to sign the webhook payload for verifying its authenticity on the receiver's end.
- `topics` (list of enum, optional) — List of event types the webhook will receive notifications for
  - Allowed values: `order.shipped`, `order.delivered`, `order.shipment.delivered`, `order.shipment.exception`, `order.shipment.on_hold`, `order.shipment.cancelled`, `order.shipment.tracking.updated`, `order.shipment.address.updated`, `order.shipment.line_item.added`, `order.shipment.line_item.removed`, `order.shipment.line_item.updated`, `order.shipment.shipping_service.updated`, `return.created`, `return.updated`, `return.completed`, `return.load_shipment.departed`, `return.gaylord.departed`, `return.load_shipment.arrived`, `return.gaylord.arrived`, `return.gaylord.stow_completed`, `billing.charge.created`, `billing.refund.created`, `billing.credit.created`, `wro.box.arrived`, `wro.box.scanned`, `wro.box.stowed`, `wro.completed`, `wro.created`, `wro.updated`
- `url` (string, optional) — URL subscription events will be posted to

## Errors

### 401 Unauthorized Error

No access right at this time

- `any`

### 403 Forbidden Error

No access

- `any`

### 422 Unprocessable Entity Error

Client Error

- `content_types` (list of string, optional, nullable)
- `declared_type` (string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string or string, optional, nullable)
- `formatters` (list of object, optional, nullable)
- `status_code` (integer, optional, nullable)
- `value` (object, optional, nullable)

## Examples

**Request**

```json
{
  "topics": [
    "order.shipped"
  ],
  "url": "https://mywebsite.com/shipbob/handler",
  "description": "string",
  "secret": "string"
}
```

**Response**

```json
{
  "created_at": "2019-08-24T14:15:22+00:00",
  "description": "string",
  "id": "12345",
  "secret": "string",
  "topics": [
    "order.shipped"
  ],
  "url": "string"
}
```

**SDK Code**

```python default
import requests

url = "https://api.shipbob.com/2026-01/webhook"

payload = {
    "topics": ["order.shipped"],
    "url": "https://mywebsite.com/shipbob/handler",
    "description": "string",
    "secret": "string"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript default
const url = 'https://api.shipbob.com/2026-01/webhook';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"topics":["order.shipped"],"url":"https://mywebsite.com/shipbob/handler","description":"string","secret":"string"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go default
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.shipbob.com/2026-01/webhook"

	payload := strings.NewReader("{\n  \"topics\": [\n    \"order.shipped\"\n  ],\n  \"url\": \"https://mywebsite.com/shipbob/handler\",\n  \"description\": \"string\",\n  \"secret\": \"string\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby default
require 'uri'
require 'net/http'

url = URI("https://api.shipbob.com/2026-01/webhook")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"topics\": [\n    \"order.shipped\"\n  ],\n  \"url\": \"https://mywebsite.com/shipbob/handler\",\n  \"description\": \"string\",\n  \"secret\": \"string\"\n}"

response = http.request(request)
puts response.read_body
```

```java default
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.shipbob.com/2026-01/webhook")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"topics\": [\n    \"order.shipped\"\n  ],\n  \"url\": \"https://mywebsite.com/shipbob/handler\",\n  \"description\": \"string\",\n  \"secret\": \"string\"\n}")
  .asString();
```

```php default
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.shipbob.com/2026-01/webhook', [
  'body' => '{
  "topics": [
    "order.shipped"
  ],
  "url": "https://mywebsite.com/shipbob/handler",
  "description": "string",
  "secret": "string"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp default
using RestSharp;

var client = new RestClient("https://api.shipbob.com/2026-01/webhook");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"topics\": [\n    \"order.shipped\"\n  ],\n  \"url\": \"https://mywebsite.com/shipbob/handler\",\n  \"description\": \"string\",\n  \"secret\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift default
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "topics": ["order.shipped"],
  "url": "https://mywebsite.com/shipbob/handler",
  "description": "string",
  "secret": "string"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.shipbob.com/2026-01/webhook")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```