Webhooks

Manage the webhook subscriptions for a carrier account (License). ShipOS POSTs a signed JSON payload to your url whenever a subscribed event fires, records every attempt as a delivery, and lets you send a test "ping". All webhook endpoints are license-scoped: they act under exactly one License, selected with license_key.

Payload signature

Every delivery is signed. ShipOS sends two headers with each POST:

X-ShipOS-Event — the event name (e.g. shipment.created).
X-ShipOS-Signature — t={timestamp},v1={hmac}, where {hmac} is HMAC-SHA256("{timestamp}.{body}") keyed with the subscription's signing secret (the whsec_… value returned once on creation). Recompute it over the raw request body to verify authenticity.

The delivered body is { "event": "...", "created_at": {unix_timestamp}, "data": { ... } }. Deliveries are retried up to 5 times with a 30-second backoff on any non-2xx response or transport error.

Subscribable events

Event	Fires when
`shipment.created`	A shipment is created.
`shipment.status_changed`	A shipment's status changes.
`shipment.delivered`	A shipment is delivered.
`shipment.cancelled`	A shipment is cancelled.

ping is also delivered by the ping endpoint as a test event, but it is not a subscribable event value.

`GET` /webhooks

List all webhook subscriptions owned by the caller's license. Auth: client credentials. License: required.

Parameters

Query

Field	Type	Required	Description
`license_key`	string	conditional	The `licenses.key` selecting the carrier account. Required when the account owns more than one active license.

Example request

bash

curl --location 'https://app.shipos.co.il/api/v2/webhooks?license_key={license_key}' \
--header 'X-Client-Id: {client_id}' \
--header 'X-Client-Secret: {client_secret}' \
--header 'Accept: application/json'

// Node.js 18+ / browsers — no dependencies
const url = new URL('https://app.shipos.co.il/api/v2/webhooks')
url.searchParams.set('license_key', '{license_key}')

const response = await fetch(url, {
  headers: {
    'X-Client-Id': process.env.SHIPOS_CLIENT_ID,
    'X-Client-Secret': process.env.SHIPOS_CLIENT_SECRET,
    Accept: 'application/json',
  },
})

if (!response.ok) {
  const { error } = await response.json()
  throw new Error(`${error.code}: ${error.message}`)
}

const { data: webhooks } = await response.json()

for (const hook of webhooks) {
  console.log(hook.id, hook.url, hook.events.join(', '))
}

php

<?php
// composer require guzzlehttp/guzzle

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.shipos.co.il/api/v2/',
    'headers' => [
        'X-Client-Id' => getenv('SHIPOS_CLIENT_ID'),
        'X-Client-Secret' => getenv('SHIPOS_CLIENT_SECRET'),
        'Accept' => 'application/json',
    ],
]);

$response = $client->get('webhooks', [
    'query' => ['license_key' => '{license_key}'],
]);

$webhooks = json_decode($response->getBody()->getContents(), true)['data'];

foreach ($webhooks as $hook) {
    echo $hook['id'], ' ', $hook['url'], ' ', implode(', ', $hook['events']), PHP_EOL;
}

php

<?php

use Illuminate\Support\Facades\Http;

$webhooks = Http::withHeaders([
    'X-Client-Id' => config('services.shipos.client_id'),
    'X-Client-Secret' => config('services.shipos.client_secret'),
])
    ->acceptJson()
    ->get('https://app.shipos.co.il/api/v2/webhooks', [
        'license_key' => '{license_key}',
    ])
    ->throw()
    ->json('data');

foreach ($webhooks as $hook) {
    logger()->info($hook['id'].' '.$hook['url'].' '.implode(', ', $hook['events']));
}

python

# pip install httpx
import os

import httpx

response = httpx.get(
    "https://app.shipos.co.il/api/v2/webhooks",
    params={"license_key": "{license_key}"},
    headers={
        "X-Client-Id": os.environ["SHIPOS_CLIENT_ID"],
        "X-Client-Secret": os.environ["SHIPOS_CLIENT_SECRET"],
        "Accept": "application/json",
    },
)
response.raise_for_status()

for hook in response.json()["data"]:
    print(hook["id"], hook["url"], ", ".join(hook["events"]))

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type webhookList struct {
	Data []struct {
		ID     string   `json:"id"`
		URL    string   `json:"url"`
		Events []string `json:"events"`
	} `json:"data"`
}

func main() {
	req, _ := http.NewRequest("GET",
		"https://app.shipos.co.il/api/v2/webhooks?license_key={license_key}", nil)
	req.Header.Set("X-Client-Id", os.Getenv("SHIPOS_CLIENT_ID"))
	req.Header.Set("X-Client-Secret", os.Getenv("SHIPOS_CLIENT_SECRET"))
	req.Header.Set("Accept", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var list webhookList
	if err := json.NewDecoder(res.Body).Decode(&list); err != nil {
		panic(err)
	}

	for _, hook := range list.Data {
		fmt.Println(hook.ID, hook.URL, hook.Events)
	}
}

java

// Java 17+ — java.net.http, no dependencies (parse with Jackson/Gson)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ShipOsListWebhooks {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(
                "https://app.shipos.co.il/api/v2/webhooks?license_key={license_key}"))
            .header("X-Client-Id", System.getenv("SHIPOS_CLIENT_ID"))
            .header("X-Client-Secret", System.getenv("SHIPOS_CLIENT_SECRET"))
            .header("Accept", "application/json")
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new RuntimeException("ShipOS error: " + response.body());
        }

        System.out.println(response.body()); // {"data":[...]} — map with Jackson/Gson
    }
}

csharp

// .NET 8+ — System.Net.Http.Json
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient
{
    BaseAddress = new Uri("https://app.shipos.co.il/api/v2/"),
};
http.DefaultRequestHeaders.Add("X-Client-Id",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_ID"));
http.DefaultRequestHeaders.Add("X-Client-Secret",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_SECRET"));

var payload = await http.GetFromJsonAsync<JsonDocument>(
    "webhooks?license_key={license_key}")
    ?? throw new InvalidOperationException("Empty response");

foreach (var hook in payload.RootElement.GetProperty("data").EnumerateArray())
{
    Console.WriteLine(
        $"{hook.GetProperty("id").GetString()} {hook.GetProperty("url").GetString()}");
}

ruby

require "net/http"
require "json"

uri = URI("https://app.shipos.co.il/api/v2/webhooks")
uri.query = URI.encode_www_form(license_key: "{license_key}")

request = Net::HTTP::Get.new(uri)
request["X-Client-Id"] = ENV.fetch("SHIPOS_CLIENT_ID")
request["X-Client-Secret"] = ENV.fetch("SHIPOS_CLIENT_SECRET")
request["Accept"] = "application/json"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

raise "ShipOS error: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

JSON.parse(response.body).fetch("data").each do |hook|
  puts "#{hook["id"]} #{hook["url"]} #{hook["events"].join(", ")}"
end

rust

// [dependencies]
// reqwest = { version = "0.12", features = ["json"] }
// tokio = { version = "1", features = ["full"] }
// serde_json = "1"
use serde_json::Value;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let payload: Value = reqwest::Client::new()
        .get("https://app.shipos.co.il/api/v2/webhooks")
        .query(&[("license_key", "{license_key}")])
        .header("X-Client-Id", std::env::var("SHIPOS_CLIENT_ID")?)
        .header("X-Client-Secret", std::env::var("SHIPOS_CLIENT_SECRET")?)
        .header("Accept", "application/json")
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

    for hook in payload["data"].as_array().unwrap_or(&Vec::new()) {
        println!("{} {} {}", hook["id"], hook["url"], hook["events"]);
    }
    Ok(())
}

Response `200`

json

{
  "data": [
    {
      "id": "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f",
      "url": "https://example.com/hooks/shipos",
      "events": ["shipment.created", "shipment.delivered"],
      "is_active": true,
      "created_at": "2026-07-01T09:00:00.000000Z",
      "updated_at": "2026-07-20T12:30:00.000000Z"
    }
  ]
}

The signing secret is not included when listing — it is only ever returned once, on creation.

Errors

Status	code	When
401	`unauthenticated`	Missing or invalid client credentials.
403	`forbidden`	The account has no active license, or the given `license_key` is not owned / is inactive / expired.
422	`validation_failed`	Account owns multiple active licenses and `license_key` was omitted.

`POST` /webhooks

Create a webhook subscription and return it with its one-time signing secret. Auth: client credentials. License: required.

Parameters

Body

Field	Type	Required	Description
`license_key`	string	conditional	The `licenses.key` selecting the carrier account (required when the account owns more than one active license).
`url`	string (URL)	yes	Destination URL that receives the signed POST. Max 2048 chars.
`events`	string[]	yes	At least one event to subscribe to. Each must be one of the subscribable events.
`events.*`	string	yes	Individual event value.

The signing secret is generated server-side (whsec_ + 40 random chars); it cannot be supplied by the client.

Example request

bash

curl --location --request POST 'https://app.shipos.co.il/api/v2/webhooks' \
--header 'X-Client-Id: {client_id}' \
--header 'X-Client-Secret: {client_secret}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
  "license_key": "{license_key}",
  "url": "https://example.com/hooks/shipos",
  "events": ["shipment.created", "shipment.delivered"]
}'

// Node.js 18+ / browsers — no dependencies
const response = await fetch('https://app.shipos.co.il/api/v2/webhooks', {
  method: 'POST',
  headers: {
    'X-Client-Id': process.env.SHIPOS_CLIENT_ID,
    'X-Client-Secret': process.env.SHIPOS_CLIENT_SECRET,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    license_key: '{license_key}',
    url: 'https://example.com/hooks/shipos',
    events: ['shipment.created', 'shipment.delivered'],
  }),
})

if (!response.ok) {
  const { error } = await response.json()
  throw new Error(`${error.code}: ${error.message}`)
}

const { data: webhook } = await response.json()

// Store webhook.secret now — it is returned only once.
console.log(webhook.id, webhook.secret)

php

<?php
// composer require guzzlehttp/guzzle

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.shipos.co.il/api/v2/',
    'headers' => [
        'X-Client-Id' => getenv('SHIPOS_CLIENT_ID'),
        'X-Client-Secret' => getenv('SHIPOS_CLIENT_SECRET'),
        'Accept' => 'application/json',
    ],
]);

$response = $client->post('webhooks', [
    'json' => [
        'license_key' => '{license_key}',
        'url' => 'https://example.com/hooks/shipos',
        'events' => ['shipment.created', 'shipment.delivered'],
    ],
]);

$webhook = json_decode($response->getBody()->getContents(), true)['data'];

// Store $webhook['secret'] now — it is returned only once.
echo $webhook['id'], ' ', $webhook['secret'], PHP_EOL;

php

<?php

use Illuminate\Support\Facades\Http;

$webhook = Http::withHeaders([
    'X-Client-Id' => config('services.shipos.client_id'),
    'X-Client-Secret' => config('services.shipos.client_secret'),
])
    ->acceptJson()
    ->post('https://app.shipos.co.il/api/v2/webhooks', [
        'license_key' => '{license_key}',
        'url' => 'https://example.com/hooks/shipos',
        'events' => ['shipment.created', 'shipment.delivered'],
    ])
    ->throw()
    ->json('data');

// Store $webhook['secret'] now — it is returned only once.
logger()->info($webhook['id'].' '.$webhook['secret']);

python

# pip install httpx
import os

import httpx

response = httpx.post(
    "https://app.shipos.co.il/api/v2/webhooks",
    headers={
        "X-Client-Id": os.environ["SHIPOS_CLIENT_ID"],
        "X-Client-Secret": os.environ["SHIPOS_CLIENT_SECRET"],
        "Accept": "application/json",
    },
    json={
        "license_key": "{license_key}",
        "url": "https://example.com/hooks/shipos",
        "events": ["shipment.created", "shipment.delivered"],
    },
)
response.raise_for_status()
webhook = response.json()["data"]

# Store webhook["secret"] now — it is returned only once.
print(webhook["id"], webhook["secret"])

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"license_key": "{license_key}",
		"url":         "https://example.com/hooks/shipos",
		"events":      []string{"shipment.created", "shipment.delivered"},
	})

	req, _ := http.NewRequest("POST",
		"https://app.shipos.co.il/api/v2/webhooks", bytes.NewReader(body))
	req.Header.Set("X-Client-Id", os.Getenv("SHIPOS_CLIENT_ID"))
	req.Header.Set("X-Client-Secret", os.Getenv("SHIPOS_CLIENT_SECRET"))
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var payload struct {
		Data struct {
			ID     string `json:"id"`
			Secret string `json:"secret"`
		} `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&payload); err != nil {
		panic(err)
	}

	// Store the secret now — it is returned only once.
	fmt.Println(payload.Data.ID, payload.Data.Secret)
}

java

// Java 17+ — java.net.http, no dependencies (parse with Jackson/Gson)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ShipOsCreateWebhook {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "license_key": "{license_key}",
              "url": "https://example.com/hooks/shipos",
              "events": ["shipment.created", "shipment.delivered"]
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.shipos.co.il/api/v2/webhooks"))
            .header("X-Client-Id", System.getenv("SHIPOS_CLIENT_ID"))
            .header("X-Client-Secret", System.getenv("SHIPOS_CLIENT_SECRET"))
            .header("Accept", "application/json")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 201) {
            throw new RuntimeException("ShipOS error: " + response.body());
        }

        System.out.println(response.body()); // contains the one-time "secret"
    }
}

csharp

// .NET 8+ — System.Net.Http.Json
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient
{
    BaseAddress = new Uri("https://app.shipos.co.il/api/v2/"),
};
http.DefaultRequestHeaders.Add("X-Client-Id",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_ID"));
http.DefaultRequestHeaders.Add("X-Client-Secret",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_SECRET"));

var response = await http.PostAsJsonAsync("webhooks", new
{
    license_key = "{license_key}",
    url = "https://example.com/hooks/shipos",
    events = new[] { "shipment.created", "shipment.delivered" },
});
response.EnsureSuccessStatusCode();

var payload = await response.Content.ReadFromJsonAsync<JsonDocument>()
    ?? throw new InvalidOperationException("Empty response");
var webhook = payload.RootElement.GetProperty("data");

// Store the secret now — it is returned only once.
Console.WriteLine(
    $"{webhook.GetProperty("id").GetString()} {webhook.GetProperty("secret").GetString()}");

ruby

require "net/http"
require "json"

uri = URI("https://app.shipos.co.il/api/v2/webhooks")

request = Net::HTTP::Post.new(uri)
request["X-Client-Id"] = ENV.fetch("SHIPOS_CLIENT_ID")
request["X-Client-Secret"] = ENV.fetch("SHIPOS_CLIENT_SECRET")
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request.body = JSON.dump(
  license_key: "{license_key}",
  url: "https://example.com/hooks/shipos",
  events: ["shipment.created", "shipment.delivered"]
)

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

raise "ShipOS error: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

webhook = JSON.parse(response.body).fetch("data")

# Store webhook["secret"] now — it is returned only once.
puts "#{webhook["id"]} #{webhook["secret"]}"

rust

// [dependencies]
// reqwest = { version = "0.12", features = ["json"] }
// tokio = { version = "1", features = ["full"] }
// serde_json = "1"
use serde_json::{json, Value};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let payload: Value = reqwest::Client::new()
        .post("https://app.shipos.co.il/api/v2/webhooks")
        .header("X-Client-Id", std::env::var("SHIPOS_CLIENT_ID")?)
        .header("X-Client-Secret", std::env::var("SHIPOS_CLIENT_SECRET")?)
        .header("Accept", "application/json")
        .json(&json!({
            "license_key": "{license_key}",
            "url": "https://example.com/hooks/shipos",
            "events": ["shipment.created", "shipment.delivered"]
        }))
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

    // Store the secret now — it is returned only once.
    println!("{} {}", payload["data"]["id"], payload["data"]["secret"]);
    Ok(())
}

Response `201`

json

{
  "data": {
    "id": "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f",
    "url": "https://example.com/hooks/shipos",
    "events": ["shipment.created", "shipment.delivered"],
    "is_active": true,
    "secret": "whsec_S0meRandom40CharSigningSecretValueHere00",
    "created_at": "2026-07-29T10:00:00.000000Z",
    "updated_at": "2026-07-29T10:00:00.000000Z"
  }
}

Store the secret now

secret is returned only in this create response. It is write-only afterwards and never appears again in GET /webhooks, updates, or any other response. Store it securely to verify the X-ShipOS-Signature header.

Errors

Status	code	When
401	`unauthenticated`	Missing or invalid client credentials.
403	`forbidden`	No active license, or the given `license_key` is not owned / is inactive / expired.
422	`validation_failed`	`url` missing/invalid/too long, `events` empty or containing an unknown event, or multiple licenses with `license_key` omitted.

`PATCH` /webhooks/

Update a webhook subscription owned by the caller's license. Partial (PATCH) semantics — send only the fields you want to change. Auth: client credentials. License: required.

Parameters

Path

Field	Type	Required	Description
`uuid`	string	yes	The webhook subscription `id` (UUID).

Body (all optional; the signing secret can never be changed)

Field	Type	Required	Description
`license_key`	string	conditional	Selects the carrier account (required with multiple active licenses).
`url`	string (URL)	no	New destination URL. Max 2048 chars.
`events`	string[]	no	Replacement event set (min 1, de-duplicated). Each must be a valid event value.
`events.*`	string	required with `events`	Individual event value.
`is_active`	boolean	no	Enable or disable the subscription.

Example request

bash

curl --location --request PATCH 'https://app.shipos.co.il/api/v2/webhooks/9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f' \
--header 'X-Client-Id: {client_id}' \
--header 'X-Client-Secret: {client_secret}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
  "license_key": "{license_key}",
  "events": ["shipment.created", "shipment.status_changed"],
  "is_active": false
}'

// Node.js 18+ / browsers — no dependencies
const uuid = '9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f'

const response = await fetch(`https://app.shipos.co.il/api/v2/webhooks/${uuid}`, {
  method: 'PATCH',
  headers: {
    'X-Client-Id': process.env.SHIPOS_CLIENT_ID,
    'X-Client-Secret': process.env.SHIPOS_CLIENT_SECRET,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    license_key: '{license_key}',
    events: ['shipment.created', 'shipment.status_changed'],
    is_active: false,
  }),
})

if (!response.ok) {
  const { error } = await response.json()
  throw new Error(`${error.code}: ${error.message}`)
}

const { data: webhook } = await response.json()

console.log(webhook.id, webhook.is_active, webhook.events.join(', '))

php

<?php
// composer require guzzlehttp/guzzle

$uuid = '9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f';

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.shipos.co.il/api/v2/',
    'headers' => [
        'X-Client-Id' => getenv('SHIPOS_CLIENT_ID'),
        'X-Client-Secret' => getenv('SHIPOS_CLIENT_SECRET'),
        'Accept' => 'application/json',
    ],
]);

$response = $client->patch("webhooks/{$uuid}", [
    'json' => [
        'license_key' => '{license_key}',
        'events' => ['shipment.created', 'shipment.status_changed'],
        'is_active' => false,
    ],
]);

$webhook = json_decode($response->getBody()->getContents(), true)['data'];

echo $webhook['id'], ' ', implode(', ', $webhook['events']), PHP_EOL;

php

<?php

use Illuminate\Support\Facades\Http;

$uuid = '9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f';

$webhook = Http::withHeaders([
    'X-Client-Id' => config('services.shipos.client_id'),
    'X-Client-Secret' => config('services.shipos.client_secret'),
])
    ->acceptJson()
    ->patch("https://app.shipos.co.il/api/v2/webhooks/{$uuid}", [
        'license_key' => '{license_key}',
        'events' => ['shipment.created', 'shipment.status_changed'],
        'is_active' => false,
    ])
    ->throw()
    ->json('data');

logger()->info($webhook['id'].' '.implode(', ', $webhook['events']));

python

# pip install httpx
import os

import httpx

uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f"

response = httpx.patch(
    f"https://app.shipos.co.il/api/v2/webhooks/{uuid}",
    headers={
        "X-Client-Id": os.environ["SHIPOS_CLIENT_ID"],
        "X-Client-Secret": os.environ["SHIPOS_CLIENT_SECRET"],
        "Accept": "application/json",
    },
    json={
        "license_key": "{license_key}",
        "events": ["shipment.created", "shipment.status_changed"],
        "is_active": False,
    },
)
response.raise_for_status()
webhook = response.json()["data"]

print(webhook["id"], webhook["is_active"], ", ".join(webhook["events"]))

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	uuid := "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f"

	body, _ := json.Marshal(map[string]any{
		"license_key": "{license_key}",
		"events":      []string{"shipment.created", "shipment.status_changed"},
		"is_active":   false,
	})

	req, _ := http.NewRequest("PATCH",
		"https://app.shipos.co.il/api/v2/webhooks/"+uuid, bytes.NewReader(body))
	req.Header.Set("X-Client-Id", os.Getenv("SHIPOS_CLIENT_ID"))
	req.Header.Set("X-Client-Secret", os.Getenv("SHIPOS_CLIENT_SECRET"))
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var payload struct {
		Data struct {
			ID       string   `json:"id"`
			Events   []string `json:"events"`
			IsActive bool     `json:"is_active"`
		} `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&payload); err != nil {
		panic(err)
	}

	fmt.Println(payload.Data.ID, payload.Data.IsActive, payload.Data.Events)
}

java

// Java 17+ — java.net.http, no dependencies (parse with Jackson/Gson)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ShipOsUpdateWebhook {
    public static void main(String[] args) throws Exception {
        String uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f";
        String body = """
            {
              "license_key": "{license_key}",
              "events": ["shipment.created", "shipment.status_changed"],
              "is_active": false
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.shipos.co.il/api/v2/webhooks/" + uuid))
            .header("X-Client-Id", System.getenv("SHIPOS_CLIENT_ID"))
            .header("X-Client-Secret", System.getenv("SHIPOS_CLIENT_SECRET"))
            .header("Accept", "application/json")
            .header("Content-Type", "application/json")
            .method("PATCH", HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new RuntimeException("ShipOS error: " + response.body());
        }

        System.out.println(response.body()); // {"data":{...}} — map with Jackson/Gson
    }
}

csharp

// .NET 8+ — System.Net.Http.Json
using System.Net.Http.Json;
using System.Text.Json;

var uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f";

using var http = new HttpClient
{
    BaseAddress = new Uri("https://app.shipos.co.il/api/v2/"),
};
http.DefaultRequestHeaders.Add("X-Client-Id",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_ID"));
http.DefaultRequestHeaders.Add("X-Client-Secret",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_SECRET"));

var response = await http.PatchAsJsonAsync($"webhooks/{uuid}", new
{
    license_key = "{license_key}",
    events = new[] { "shipment.created", "shipment.status_changed" },
    is_active = false,
});
response.EnsureSuccessStatusCode();

var payload = await response.Content.ReadFromJsonAsync<JsonDocument>()
    ?? throw new InvalidOperationException("Empty response");
var webhook = payload.RootElement.GetProperty("data");

Console.WriteLine(
    $"{webhook.GetProperty("id").GetString()} {webhook.GetProperty("is_active").GetBoolean()}");

ruby

require "net/http"
require "json"

uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f"
uri = URI("https://app.shipos.co.il/api/v2/webhooks/#{uuid}")

request = Net::HTTP::Patch.new(uri)
request["X-Client-Id"] = ENV.fetch("SHIPOS_CLIENT_ID")
request["X-Client-Secret"] = ENV.fetch("SHIPOS_CLIENT_SECRET")
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request.body = JSON.dump(
  license_key: "{license_key}",
  events: ["shipment.created", "shipment.status_changed"],
  is_active: false
)

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

raise "ShipOS error: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

webhook = JSON.parse(response.body).fetch("data")

puts "#{webhook["id"]} #{webhook["is_active"]} #{webhook["events"].join(", ")}"

rust

// [dependencies]
// reqwest = { version = "0.12", features = ["json"] }
// tokio = { version = "1", features = ["full"] }
// serde_json = "1"
use serde_json::{json, Value};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f";

    let payload: Value = reqwest::Client::new()
        .patch(format!("https://app.shipos.co.il/api/v2/webhooks/{uuid}"))
        .header("X-Client-Id", std::env::var("SHIPOS_CLIENT_ID")?)
        .header("X-Client-Secret", std::env::var("SHIPOS_CLIENT_SECRET")?)
        .header("Accept", "application/json")
        .json(&json!({
            "license_key": "{license_key}",
            "events": ["shipment.created", "shipment.status_changed"],
            "is_active": false
        }))
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

    let webhook = &payload["data"];
    println!("{} {} {}", webhook["id"], webhook["is_active"], webhook["events"]);
    Ok(())
}

Response `200`

json

{
  "data": {
    "id": "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f",
    "url": "https://example.com/hooks/shipos",
    "events": ["shipment.created", "shipment.status_changed"],
    "is_active": false,
    "created_at": "2026-07-01T09:00:00.000000Z",
    "updated_at": "2026-07-29T10:05:00.000000Z"
  }
}

Errors

Status	code	When
401	`unauthenticated`	Missing or invalid client credentials.
403	`forbidden`	No active license, or `license_key` not owned / inactive / expired.
404	`not_found`	No webhook with that `uuid` belongs to the caller's license.
422	`validation_failed`	Invalid `url`, empty/invalid `events`, or multiple licenses with `license_key` omitted.

`POST` /webhooks/{uuid}/ping

Queue a test ping event delivery to the subscription's URL. Useful for verifying your endpoint and signature check. Auth: client credentials. License: required.

The delivered body is { "event": "ping", "created_at": {timestamp}, "data": { "message": "This is a test event from ShipOS." } }, signed exactly like a real event.

Parameters

Path

Field	Type	Required	Description
`uuid`	string	yes	The webhook subscription `id` (UUID).

Query / Body

Field	Type	Required	Description
`license_key`	string	conditional	Selects the carrier account (required with multiple active licenses).

Example request

bash

curl --location --request POST 'https://app.shipos.co.il/api/v2/webhooks/9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f/ping' \
--header 'X-Client-Id: {client_id}' \
--header 'X-Client-Secret: {client_secret}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{ "license_key": "{license_key}" }'

// Node.js 18+ / browsers — no dependencies
const uuid = '9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f'

const response = await fetch(
  `https://app.shipos.co.il/api/v2/webhooks/${uuid}/ping`,
  {
    method: 'POST',
    headers: {
      'X-Client-Id': process.env.SHIPOS_CLIENT_ID,
      'X-Client-Secret': process.env.SHIPOS_CLIENT_SECRET,
      Accept: 'application/json',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ license_key: '{license_key}' }),
  },
)

if (!response.ok) {
  const { error } = await response.json()
  throw new Error(`${error.code}: ${error.message}`)
}

const { data } = await response.json()

console.log(data.queued) // true — enqueued, not yet accepted by the receiver

php

<?php
// composer require guzzlehttp/guzzle

$uuid = '9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f';

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.shipos.co.il/api/v2/',
    'headers' => [
        'X-Client-Id' => getenv('SHIPOS_CLIENT_ID'),
        'X-Client-Secret' => getenv('SHIPOS_CLIENT_SECRET'),
        'Accept' => 'application/json',
    ],
]);

$response = $client->post("webhooks/{$uuid}/ping", [
    'json' => ['license_key' => '{license_key}'],
]);

$data = json_decode($response->getBody()->getContents(), true)['data'];

var_dump($data['queued']);

php

<?php

use Illuminate\Support\Facades\Http;

$uuid = '9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f';

$queued = Http::withHeaders([
    'X-Client-Id' => config('services.shipos.client_id'),
    'X-Client-Secret' => config('services.shipos.client_secret'),
])
    ->acceptJson()
    ->post("https://app.shipos.co.il/api/v2/webhooks/{$uuid}/ping", [
        'license_key' => '{license_key}',
    ])
    ->throw()
    ->json('data.queued');

logger()->info('ping queued: '.var_export($queued, true));

python

# pip install httpx
import os

import httpx

uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f"

response = httpx.post(
    f"https://app.shipos.co.il/api/v2/webhooks/{uuid}/ping",
    headers={
        "X-Client-Id": os.environ["SHIPOS_CLIENT_ID"],
        "X-Client-Secret": os.environ["SHIPOS_CLIENT_SECRET"],
        "Accept": "application/json",
    },
    json={"license_key": "{license_key}"},
)
response.raise_for_status()

print(response.json()["data"]["queued"])

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	uuid := "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f"

	body, _ := json.Marshal(map[string]string{"license_key": "{license_key}"})

	req, _ := http.NewRequest("POST",
		"https://app.shipos.co.il/api/v2/webhooks/"+uuid+"/ping",
		bytes.NewReader(body))
	req.Header.Set("X-Client-Id", os.Getenv("SHIPOS_CLIENT_ID"))
	req.Header.Set("X-Client-Secret", os.Getenv("SHIPOS_CLIENT_SECRET"))
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var payload struct {
		Data struct {
			Queued bool `json:"queued"`
		} `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&payload); err != nil {
		panic(err)
	}

	fmt.Println(payload.Data.Queued)
}

java

// Java 17+ — java.net.http, no dependencies (parse with Jackson/Gson)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ShipOsPingWebhook {
    public static void main(String[] args) throws Exception {
        String uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f";
        String body = "{\"license_key\": \"{license_key}\"}";

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(
                "https://app.shipos.co.il/api/v2/webhooks/" + uuid + "/ping"))
            .header("X-Client-Id", System.getenv("SHIPOS_CLIENT_ID"))
            .header("X-Client-Secret", System.getenv("SHIPOS_CLIENT_SECRET"))
            .header("Accept", "application/json")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new RuntimeException("ShipOS error: " + response.body());
        }

        System.out.println(response.body()); // {"data":{"queued":true}}
    }
}

csharp

// .NET 8+ — System.Net.Http.Json
using System.Net.Http.Json;
using System.Text.Json;

var uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f";

using var http = new HttpClient
{
    BaseAddress = new Uri("https://app.shipos.co.il/api/v2/"),
};
http.DefaultRequestHeaders.Add("X-Client-Id",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_ID"));
http.DefaultRequestHeaders.Add("X-Client-Secret",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_SECRET"));

var response = await http.PostAsJsonAsync($"webhooks/{uuid}/ping", new
{
    license_key = "{license_key}",
});
response.EnsureSuccessStatusCode();

var payload = await response.Content.ReadFromJsonAsync<JsonDocument>()
    ?? throw new InvalidOperationException("Empty response");

Console.WriteLine(
    payload.RootElement.GetProperty("data").GetProperty("queued").GetBoolean());

ruby

require "net/http"
require "json"

uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f"
uri = URI("https://app.shipos.co.il/api/v2/webhooks/#{uuid}/ping")

request = Net::HTTP::Post.new(uri)
request["X-Client-Id"] = ENV.fetch("SHIPOS_CLIENT_ID")
request["X-Client-Secret"] = ENV.fetch("SHIPOS_CLIENT_SECRET")
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request.body = JSON.dump(license_key: "{license_key}")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

raise "ShipOS error: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

puts JSON.parse(response.body).dig("data", "queued")

rust

// [dependencies]
// reqwest = { version = "0.12", features = ["json"] }
// tokio = { version = "1", features = ["full"] }
// serde_json = "1"
use serde_json::{json, Value};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f";

    let payload: Value = reqwest::Client::new()
        .post(format!("https://app.shipos.co.il/api/v2/webhooks/{uuid}/ping"))
        .header("X-Client-Id", std::env::var("SHIPOS_CLIENT_ID")?)
        .header("X-Client-Secret", std::env::var("SHIPOS_CLIENT_SECRET")?)
        .header("Accept", "application/json")
        .json(&json!({ "license_key": "{license_key}" }))
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

    println!("{}", payload["data"]["queued"]);
    Ok(())
}

Response `200`

json

{ "data": { "queued": true } }

The delivery is dispatched asynchronously; queued: true confirms it was enqueued, not that the receiver accepted it. Check GET /webhooks/{uuid}/deliveries for the outcome.

Errors

Status	code	When
401	`unauthenticated`	Missing or invalid client credentials.
403	`forbidden`	No active license, or `license_key` not owned / inactive / expired.
404	`not_found`	No webhook with that `uuid` belongs to the caller's license.

`GET` /webhooks/{uuid}/deliveries

List the paginated delivery attempts for a webhook subscription (newest per the repository ordering). Auth: client credentials. License: required.

Parameters

Path

Field	Type	Required	Description
`uuid`	string	yes	The webhook subscription `id` (UUID).

Query

Field	Type	Required	Description
`license_key`	string	conditional	Selects the carrier account (required with multiple active licenses).
`per_page`	int	no	Items per page. Default 25, capped at 100.

Example request

bash

curl --location 'https://app.shipos.co.il/api/v2/webhooks/9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f/deliveries?license_key={license_key}&per_page=50' \
--header 'X-Client-Id: {client_id}' \
--header 'X-Client-Secret: {client_secret}' \
--header 'Accept: application/json'

// Node.js 18+ / browsers — no dependencies
const uuid = '9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f'
const url = new URL(
  `https://app.shipos.co.il/api/v2/webhooks/${uuid}/deliveries`,
)
url.searchParams.set('license_key', '{license_key}')
url.searchParams.set('per_page', '50')

const response = await fetch(url, {
  headers: {
    'X-Client-Id': process.env.SHIPOS_CLIENT_ID,
    'X-Client-Secret': process.env.SHIPOS_CLIENT_SECRET,
    Accept: 'application/json',
  },
})

if (!response.ok) {
  const { error } = await response.json()
  throw new Error(`${error.code}: ${error.message}`)
}

const { data: deliveries } = await response.json()

for (const attempt of deliveries) {
  console.log(attempt.event, attempt.attempt, attempt.status_code, attempt.success)
}

php

<?php
// composer require guzzlehttp/guzzle

$uuid = '9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f';

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.shipos.co.il/api/v2/',
    'headers' => [
        'X-Client-Id' => getenv('SHIPOS_CLIENT_ID'),
        'X-Client-Secret' => getenv('SHIPOS_CLIENT_SECRET'),
        'Accept' => 'application/json',
    ],
]);

$response = $client->get("webhooks/{$uuid}/deliveries", [
    'query' => ['license_key' => '{license_key}', 'per_page' => 50],
]);

$deliveries = json_decode($response->getBody()->getContents(), true)['data'];

foreach ($deliveries as $attempt) {
    echo $attempt['event'], ' #', $attempt['attempt'], ' ', $attempt['status_code'], PHP_EOL;
}

php

<?php

use Illuminate\Support\Facades\Http;

$uuid = '9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f';

$deliveries = Http::withHeaders([
    'X-Client-Id' => config('services.shipos.client_id'),
    'X-Client-Secret' => config('services.shipos.client_secret'),
])
    ->acceptJson()
    ->get("https://app.shipos.co.il/api/v2/webhooks/{$uuid}/deliveries", [
        'license_key' => '{license_key}',
        'per_page' => 50,
    ])
    ->throw()
    ->json('data');

foreach ($deliveries as $attempt) {
    logger()->info($attempt['event'].' #'.$attempt['attempt'].' '.$attempt['status_code']);
}

python

# pip install httpx
import os

import httpx

uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f"

response = httpx.get(
    f"https://app.shipos.co.il/api/v2/webhooks/{uuid}/deliveries",
    params={"license_key": "{license_key}", "per_page": 50},
    headers={
        "X-Client-Id": os.environ["SHIPOS_CLIENT_ID"],
        "X-Client-Secret": os.environ["SHIPOS_CLIENT_SECRET"],
        "Accept": "application/json",
    },
)
response.raise_for_status()

for attempt in response.json()["data"]:
    print(attempt["event"], attempt["attempt"], attempt["status_code"], attempt["success"])

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

type deliveryList struct {
	Data []struct {
		Event      string `json:"event"`
		Attempt    int    `json:"attempt"`
		StatusCode *int   `json:"status_code"`
		Success    bool   `json:"success"`
	} `json:"data"`
}

func main() {
	uuid := "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f"

	req, _ := http.NewRequest("GET",
		"https://app.shipos.co.il/api/v2/webhooks/"+uuid+
			"/deliveries?license_key={license_key}&per_page=50", nil)
	req.Header.Set("X-Client-Id", os.Getenv("SHIPOS_CLIENT_ID"))
	req.Header.Set("X-Client-Secret", os.Getenv("SHIPOS_CLIENT_SECRET"))
	req.Header.Set("Accept", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var list deliveryList
	if err := json.NewDecoder(res.Body).Decode(&list); err != nil {
		panic(err)
	}

	for _, attempt := range list.Data {
		fmt.Println(attempt.Event, attempt.Attempt, attempt.Success)
	}
}

java

// Java 17+ — java.net.http, no dependencies (parse with Jackson/Gson)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ShipOsWebhookDeliveries {
    public static void main(String[] args) throws Exception {
        String uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f";

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.shipos.co.il/api/v2/webhooks/" + uuid
                + "/deliveries?license_key={license_key}&per_page=50"))
            .header("X-Client-Id", System.getenv("SHIPOS_CLIENT_ID"))
            .header("X-Client-Secret", System.getenv("SHIPOS_CLIENT_SECRET"))
            .header("Accept", "application/json")
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new RuntimeException("ShipOS error: " + response.body());
        }

        System.out.println(response.body()); // {"data":[...]} — map with Jackson/Gson
    }
}

csharp

// .NET 8+ — System.Net.Http.Json
using System.Net.Http.Json;
using System.Text.Json;

var uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f";

using var http = new HttpClient
{
    BaseAddress = new Uri("https://app.shipos.co.il/api/v2/"),
};
http.DefaultRequestHeaders.Add("X-Client-Id",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_ID"));
http.DefaultRequestHeaders.Add("X-Client-Secret",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_SECRET"));

var payload = await http.GetFromJsonAsync<JsonDocument>(
    $"webhooks/{uuid}/deliveries?license_key={{license_key}}&per_page=50")
    ?? throw new InvalidOperationException("Empty response");

foreach (var attempt in payload.RootElement.GetProperty("data").EnumerateArray())
{
    Console.WriteLine(
        $"{attempt.GetProperty("event").GetString()} #{attempt.GetProperty("attempt").GetInt32()} {attempt.GetProperty("success").GetBoolean()}");
}

ruby

require "net/http"
require "json"

uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f"
uri = URI("https://app.shipos.co.il/api/v2/webhooks/#{uuid}/deliveries")
uri.query = URI.encode_www_form(license_key: "{license_key}", per_page: 50)

request = Net::HTTP::Get.new(uri)
request["X-Client-Id"] = ENV.fetch("SHIPOS_CLIENT_ID")
request["X-Client-Secret"] = ENV.fetch("SHIPOS_CLIENT_SECRET")
request["Accept"] = "application/json"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

raise "ShipOS error: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

JSON.parse(response.body).fetch("data").each do |attempt|
  puts "#{attempt["event"]} ##{attempt["attempt"]} #{attempt["status_code"]} #{attempt["success"]}"
end

rust

// [dependencies]
// reqwest = { version = "0.12", features = ["json"] }
// tokio = { version = "1", features = ["full"] }
// serde_json = "1"
use serde_json::Value;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f";

    let payload: Value = reqwest::Client::new()
        .get(format!("https://app.shipos.co.il/api/v2/webhooks/{uuid}/deliveries"))
        .query(&[("license_key", "{license_key}"), ("per_page", "50")])
        .header("X-Client-Id", std::env::var("SHIPOS_CLIENT_ID")?)
        .header("X-Client-Secret", std::env::var("SHIPOS_CLIENT_SECRET")?)
        .header("Accept", "application/json")
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

    for attempt in payload["data"].as_array().unwrap_or(&Vec::new()) {
        println!("{} {} {}", attempt["event"], attempt["attempt"], attempt["success"]);
    }
    Ok(())
}

Response `200`

json

{
  "data": [
    {
      "id": 4821,
      "event": "shipment.created",
      "attempt": 1,
      "status_code": 200,
      "success": true,
      "error": null,
      "created_at": "2026-07-29T10:00:01.000000Z",
      "updated_at": "2026-07-29T10:00:01.000000Z"
    },
    {
      "id": 4822,
      "event": "shipment.delivered",
      "attempt": 2,
      "status_code": 500,
      "success": false,
      "error": "HTTP 500",
      "created_at": "2026-07-29T11:00:31.000000Z",
      "updated_at": "2026-07-29T11:00:31.000000Z"
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "per_page": 50, "total": 2 }
}

Delivery fields

Field	Type	Description
`id`	int	Delivery attempt id.
`event`	string	The event name delivered (including `ping`).
`attempt`	int	Attempt number (retries increment this).
`status_code`	int \| null	HTTP status returned by your endpoint, or `null` on a transport failure.
`success`	bool	Whether the attempt succeeded (2xx).
`error`	string \| null	Failure reason (e.g. `HTTP 500` or an exception message), or `null` on success.
`created_at`	string	Attempt timestamp.
`updated_at`	string	Row update timestamp.

Standard Laravel pagination links/meta accompany the collection.

Errors

Status	code	When
401	`unauthenticated`	Missing or invalid client credentials.
403	`forbidden`	No active license, or `license_key` not owned / inactive / expired.
404	`not_found`	No webhook with that `uuid` belongs to the caller's license.

`DELETE` /webhooks/

Delete a webhook subscription owned by the caller's license. Auth: client credentials. License: required.

Parameters

Path

Field	Type	Required	Description
`uuid`	string	yes	The webhook subscription `id` (UUID).

Query / Body

Field	Type	Required	Description
`license_key`	string	conditional	Selects the carrier account (required with multiple active licenses).

Example request

bash

curl --location --request DELETE 'https://app.shipos.co.il/api/v2/webhooks/9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f?license_key={license_key}' \
--header 'X-Client-Id: {client_id}' \
--header 'X-Client-Secret: {client_secret}' \
--header 'Accept: application/json'

// Node.js 18+ / browsers — no dependencies
const uuid = '9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f'
const url = new URL(`https://app.shipos.co.il/api/v2/webhooks/${uuid}`)
url.searchParams.set('license_key', '{license_key}')

const response = await fetch(url, {
  method: 'DELETE',
  headers: {
    'X-Client-Id': process.env.SHIPOS_CLIENT_ID,
    'X-Client-Secret': process.env.SHIPOS_CLIENT_SECRET,
    Accept: 'application/json',
  },
})

if (!response.ok) {
  const { error } = await response.json()
  throw new Error(`${error.code}: ${error.message}`)
}

const { data } = await response.json()

console.log(data.deleted) // true — 200, not 204

php

<?php
// composer require guzzlehttp/guzzle

$uuid = '9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f';

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.shipos.co.il/api/v2/',
    'headers' => [
        'X-Client-Id' => getenv('SHIPOS_CLIENT_ID'),
        'X-Client-Secret' => getenv('SHIPOS_CLIENT_SECRET'),
        'Accept' => 'application/json',
    ],
]);

$response = $client->delete("webhooks/{$uuid}", [
    'query' => ['license_key' => '{license_key}'],
]);

$data = json_decode($response->getBody()->getContents(), true)['data'];

var_dump($data['deleted']);

php

<?php

use Illuminate\Support\Facades\Http;

$uuid = '9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f';

$deleted = Http::withHeaders([
    'X-Client-Id' => config('services.shipos.client_id'),
    'X-Client-Secret' => config('services.shipos.client_secret'),
])
    ->acceptJson()
    ->delete("https://app.shipos.co.il/api/v2/webhooks/{$uuid}?license_key={license_key}")
    ->throw()
    ->json('data.deleted');

logger()->info('deleted: '.var_export($deleted, true));

python

# pip install httpx
import os

import httpx

uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f"

response = httpx.request(
    "DELETE",
    f"https://app.shipos.co.il/api/v2/webhooks/{uuid}",
    params={"license_key": "{license_key}"},
    headers={
        "X-Client-Id": os.environ["SHIPOS_CLIENT_ID"],
        "X-Client-Secret": os.environ["SHIPOS_CLIENT_SECRET"],
        "Accept": "application/json",
    },
)
response.raise_for_status()

print(response.json()["data"]["deleted"])

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	uuid := "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f"

	req, _ := http.NewRequest("DELETE",
		"https://app.shipos.co.il/api/v2/webhooks/"+uuid+
			"?license_key={license_key}", nil)
	req.Header.Set("X-Client-Id", os.Getenv("SHIPOS_CLIENT_ID"))
	req.Header.Set("X-Client-Secret", os.Getenv("SHIPOS_CLIENT_SECRET"))
	req.Header.Set("Accept", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var payload struct {
		Data struct {
			Deleted bool `json:"deleted"`
		} `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&payload); err != nil {
		panic(err)
	}

	fmt.Println(payload.Data.Deleted)
}

java

// Java 17+ — java.net.http, no dependencies (parse with Jackson/Gson)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ShipOsDeleteWebhook {
    public static void main(String[] args) throws Exception {
        String uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f";

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.shipos.co.il/api/v2/webhooks/" + uuid
                + "?license_key={license_key}"))
            .header("X-Client-Id", System.getenv("SHIPOS_CLIENT_ID"))
            .header("X-Client-Secret", System.getenv("SHIPOS_CLIENT_SECRET"))
            .header("Accept", "application/json")
            .DELETE()
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new RuntimeException("ShipOS error: " + response.body());
        }

        System.out.println(response.body()); // {"data":{"deleted":true}}
    }
}

csharp

// .NET 8+ — System.Net.Http.Json
using System.Net.Http.Json;
using System.Text.Json;

var uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f";

using var http = new HttpClient
{
    BaseAddress = new Uri("https://app.shipos.co.il/api/v2/"),
};
http.DefaultRequestHeaders.Add("X-Client-Id",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_ID"));
http.DefaultRequestHeaders.Add("X-Client-Secret",
    Environment.GetEnvironmentVariable("SHIPOS_CLIENT_SECRET"));

var response = await http.DeleteAsync(
    $"webhooks/{uuid}?license_key={{license_key}}");
response.EnsureSuccessStatusCode();

var payload = await response.Content.ReadFromJsonAsync<JsonDocument>()
    ?? throw new InvalidOperationException("Empty response");

Console.WriteLine(
    payload.RootElement.GetProperty("data").GetProperty("deleted").GetBoolean());

ruby

require "net/http"
require "json"

uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f"
uri = URI("https://app.shipos.co.il/api/v2/webhooks/#{uuid}")
uri.query = URI.encode_www_form(license_key: "{license_key}")

request = Net::HTTP::Delete.new(uri)
request["X-Client-Id"] = ENV.fetch("SHIPOS_CLIENT_ID")
request["X-Client-Secret"] = ENV.fetch("SHIPOS_CLIENT_SECRET")
request["Accept"] = "application/json"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

raise "ShipOS error: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

puts JSON.parse(response.body).dig("data", "deleted")

rust

// [dependencies]
// reqwest = { version = "0.12", features = ["json"] }
// tokio = { version = "1", features = ["full"] }
// serde_json = "1"
use serde_json::Value;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let uuid = "9f2c1a7e-6b4d-4c2a-8e1f-7d3b2a1c0e9f";

    let payload: Value = reqwest::Client::new()
        .delete(format!("https://app.shipos.co.il/api/v2/webhooks/{uuid}"))
        .query(&[("license_key", "{license_key}")])
        .header("X-Client-Id", std::env::var("SHIPOS_CLIENT_ID")?)
        .header("X-Client-Secret", std::env::var("SHIPOS_CLIENT_SECRET")?)
        .header("Accept", "application/json")
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

    println!("{}", payload["data"]["deleted"]);
    Ok(())
}

Response `200`

Delete returns a JSON confirmation with a 200 status (not 204):

json

{ "data": { "deleted": true } }

Errors

Status	code	When
401	`unauthenticated`	Missing or invalid client credentials.
403	`forbidden`	No active license, or `license_key` not owned / inactive / expired.
404	`not_found`	No webhook with that `uuid` belongs to the caller's license.

Webhooks ​

Subscribable events ​

GET /webhooks ​

Parameters ​

Example request ​

Response 200 ​

Errors ​

POST /webhooks ​

Parameters ​

Example request ​

Response 201 ​

Errors ​

PATCH /webhooks/ ​

Parameters ​

Example request ​

Response 200 ​

Errors ​

POST /webhooks/{uuid}/ping ​

Parameters ​

Example request ​

Response 200 ​

Errors ​

GET /webhooks/{uuid}/deliveries ​

Parameters ​

Example request ​

Response 200 ​

Errors ​

DELETE /webhooks/ ​

Parameters ​

Example request ​

Response 200 ​

Errors ​

Webhooks

Subscribable events

`GET` /webhooks

Parameters

Example request

Response `200`

Errors

`POST` /webhooks

Parameters

Example request

Response `201`

Errors

`PATCH` /webhooks/

Parameters

Example request

Response `200`

Errors

`POST` /webhooks/{uuid}/ping

Parameters

Example request

Response `200`

Errors

`GET` /webhooks/{uuid}/deliveries

Parameters

Example request

Response `200`

Errors

`DELETE` /webhooks/

Parameters

Example request

Response `200`

Errors