Update Webhook Subscription

Updates an existing webhook subscription with new settings.

Endpoint

PUT /v1/webhook-subscriptions/{id}

Authentication

API key required. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Path Parameters

Parameter	Type	Description
id	string	The ID of the webhook subscription to update.

Request Body

Parameter	Type	Required	Description
name	string	Yes	A descriptive name for the webhook subscription.
url	string	No	The URL that will receive webhook notifications
events	array	No	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, the current secret will be preserved.
active	boolean	No	Whether the webhook subscription is active.

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": "Updated Webhook Name",
  "url": "https://example.com/webhooks/updated-endpoint",
  "events": [
    "shipping_channel.created",
    "shipping_channel.updated",
    "shipping_channel.deleted",
    "shipping_channel.status_changed",
    "tracking_parcel.status_changed"
  ],
  "active": true
}

Note: If you don't include the secret parameter, the existing secret will be preserved. To update the secret, include the secret parameter with a new value.

Response

200 OK

{
  "data": {
    "id": "wh_123456",
    "name": "Updated Webhook Name",
    "url": "https://example.com/webhooks/updated-endpoint",
    "events": [
      "shipping_channel.created",
      "shipping_channel.updated",
      "shipping_channel.deleted",
      "shipping_channel.status_changed",
      "tracking_parcel.status_changed"
    ],
    "secret": "••••••••••••••••",
    "active": true,
    "created_at": "2025-03-29T16:00:00Z",
    "updated_at": "2025-04-07T15: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
403	Forbidden - You don't have permission to update this webhook subscription
404	Not Found - The specified webhook subscription could not be found
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 must be an array."
      ]
    }
  }
}

Example Request

cURL

curl -X PUT \
  https://api.shipping-channels.com/v1/webhook-subscriptions/wh_123456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Webhook Name",
    "url": "https://example.com/webhooks/updated-endpoint",
    "events": [
      "shipping_channel.created",
      "shipping_channel.updated",
      "shipping_channel.deleted",
      "shipping_channel.status_changed",
      "tracking_parcel.status_changed"
    ],
    "active": true
  }'

PHP

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

$response = $client->request('PUT', 'https://api.shipping-channels.com/v1/webhook-subscriptions/wh_123456', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'name' => 'Updated Webhook Name',
        'url' => 'https://example.com/webhooks/updated-endpoint',
        'events' => [
            'shipping_channel.created',
            'shipping_channel.updated',
            'shipping_channel.deleted',
            'shipping_channel.status_changed',
            'tracking_parcel.status_changed',
        ],
        'active' => true,
    ],
]);

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

JavaScript

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