Create Webhook Subscription

Creates a new webhook subscription for receiving notifications about events in your account.

Endpoint

POST /v1/webhook-subscriptions

Authentication

API key required. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request Body

Parameter	Type	Required	Description
name	string	Yes	A descriptive name for the webhook subscription.
url	string	Yes	The URL that will receive webhook notifications
events	array	Yes	Array of event types to subscribe to
secret	string	No	A secret key used to sign webhook payloads. Must be at least 8 characters. If left empty, a random secret will be generated.
active	boolean	No	Whether the webhook subscription is active. Default is true.

Available Events

Event	Description
shipping_channel.created	Fires when a new shipping channel is created
shipping_channel.updated	Fires when a shipping channel is updated
shipping_channel.deleted	Fires when a shipping channel is deleted
shipping_channel.validated	Fires when a shipping channel is successfully validated
shipping_channel.status_changed	Fires when a shipping channel's status changes
tracking_parcel.created	Fires when a new tracking parcel is created
tracking_parcel.updated	Fires when a tracking parcel is updated
tracking_parcel.deleted	Fires when a tracking parcel is deleted
tracking_parcel.status_changed	Fires when a tracking parcel's status changes

Example Request Body

{
  "name": "Shipping Channel Updates",
  "url": "https://example.com/webhooks/shipping-channels",
  "events": [
    "shipping_channel.created",
    "shipping_channel.updated",
    "shipping_channel.deleted",
    "shipping_channel.status_changed"
  ],
  "secret": "your-webhook-secret",
  "active": true
}

Response

201 Created

{
  "data": {
    "id": "wh_123456",
    "name": "Shipping Channel Updates",
    "url": "https://example.com/webhooks/shipping-channels",
    "events": [
      "shipping_channel.created",
      "shipping_channel.updated",
      "shipping_channel.deleted",
      "shipping_channel.status_changed"
    ],
    "secret": "••••••••••••••••",
    "active": true,
    "created_at": "2025-04-07T12:00:00Z",
    "updated_at": "2025-04-07T12:00:00Z"
  }
}

Note: For security reasons, the webhook secret is masked in the response.

Error Responses

Status Code	Description
400	Bad Request - Invalid input parameters
401	Unauthorized - Invalid or missing API key
422	Unprocessable Entity - Validation errors
429	Too Many Requests - Rate limit exceeded
500	Server Error - Something went wrong on our end

Validation Errors

If there are validation errors, the response will include details:

{
  "error": {
    "message": "The given data was invalid.",
    "errors": {
      "url": [
        "The url must be a valid URL."
      ],
      "events": [
        "The events field is required."
      ]
    }
  }
}

Example Request

cURL

curl -X POST \
  https://api.shipping-channels.com/v1/webhook-subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shipping Channel Updates",
    "url": "https://example.com/webhooks/shipping-channels",
    "events": [
      "shipping_channel.created",
      "shipping_channel.updated",
      "shipping_channel.deleted",
      "shipping_channel.status_changed"
    ],
    "secret": "your-webhook-secret",
    "active": true
  }'

PHP

<?php
$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.shipping-channels.com/v1/webhook-subscriptions', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'name' => 'Shipping Channel Updates',
        'url' => 'https://example.com/webhooks/shipping-channels',
        'events' => [
            'shipping_channel.created',
            'shipping_channel.updated',
            'shipping_channel.deleted',
            'shipping_channel.status_changed',
        ],
        'secret' => 'your-webhook-secret',
        'active' => true,
    ],
]);

$data = json_decode($response->getBody(), true);

JavaScript

fetch('https://api.shipping-channels.com/v1/webhook-subscriptions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    name: 'Shipping Channel Updates',
    url: 'https://example.com/webhooks/shipping-channels',
    events: [
      'shipping_channel.created',
      'shipping_channel.updated',
      'shipping_channel.deleted',
      'shipping_channel.status_changed'
    ],
    secret: 'your-webhook-secret',
    active: true
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Webhook Security

We strongly recommend providing a secret when creating a webhook subscription. This secret is used to sign the webhook payloads sent to your URL, allowing you to verify that the webhook came from our service. For details on verifying webhook signatures, see the Webhooks Guide.