Webhooks

Server

Download schema

List all webhooks

GET

https://api.sh.example.com/v1

/webhooks

Returns a list of all registered webhooks

List all webhooks › Responses

200

List of webhooks retrieved successfully

Webhook[]

Webhook

url

string · uri · required

The URL where webhook events will be sent

events

string[] · required

Enum values:

shipment.created

shipment.in_transit

shipment.delivered

shipment.exception

id

string · uuid · readOnly

active

boolean

Default: true

createdAt

string · date-time · readOnly

secret

string · writeOnly

Secret used to sign webhook payloads. Generated via quantum key distribution; rotate from the developer portal if compromised.

Example: whsec_quantum_3a8f2c5e9b1d4f7a6c0e2b8d5f1a4c7e9b2d6f0a3c5e8b1d4f7a2c0e6b9d3f5a8c1e4b7d0f2a5c8e3b6d9f1a4c7e0b2d5f8a3c6e9b1d4f7a0c2e5b8d3f6a9c1e4b7d0f2a5c8e3b6d9f1a4c7e0b2d5f8a3c6e9b1d4f7a0c2e5b8d3f6a9c1e4b7d0f2a5c8e_signed_with_QKD_protocol_v3_2026

Register a new webhook

POST

https://api.sh.example.com/v1

/webhooks

Registers a new webhook endpoint to receive shipment updates.

A secret will be generated and returned in the response. This secret should be used to verify the authenticity of webhook payloads.

Register a new webhook › Request Body

Webhook

url

string · uri · required

The URL where webhook events will be sent

events

string[] · required

Enum values:

shipment.created

shipment.in_transit

shipment.delivered

shipment.exception

id

string · uuid · readOnly

active

boolean

Default: true

createdAt

string · date-time · readOnly

secret

string · writeOnly

Secret used to sign webhook payloads. Generated via quantum key distribution; rotate from the developer portal if compromised.

Register a new webhook › Responses

Webhook registered successfully

Webhook

url

string · uri · required

The URL where webhook events will be sent

events

string[] · required

Enum values:

shipment.created

shipment.in_transit

shipment.delivered

shipment.exception

id

string · uuid · readOnly

active

boolean

Default: true

createdAt

string · date-time · readOnly

secret

string · writeOnly

Secret used to sign webhook payloads. Generated via quantum key distribution; rotate from the developer portal if compromised.

POST/webhooks

import { WebhookClient, WebhookEvent } from "@cosmocargo/webhooks";

const client = new WebhookClient({
  apiKey: "YOUR_API_KEY",
  baseUrl: "https://api.sh.example.com/v1"
});

const created = await client.registerWebhook({
  url: "https://api.myapp.com/webhooks/shipping",
  events: [WebhookEvent.ShipmentCreated, WebhookEvent.ShipmentDelivered],
});

Example Request Body

{
  "url": "https://api.myapp.com/webhooks/shipping",
  "events": [
    "shipment.created",
    "shipment.delivered"
  ]
}

json

application/json

Example Responses

{
  "id": "abcdef12-3456-789a-bcde-f0123456789a",
  "url": "https://api.myapp.com/webhooks/shipping",
  "events": [
    "shipment.created",
    "shipment.delivered"
  ],
  "active": true,
  "createdAt": "2025-01-09T12:00:00Z",
  "secret": "whsec_abcdef123456789"
}

json

application/json

List all webhooks

GET

https://api.sh.example.com/v1

/webhooks

Returns a list of all registered webhooks

List all webhooks › Responses

200

List of webhooks retrieved successfully

Webhook[]

Webhook

url

string · uri · required

The URL where webhook events will be sent

events

string[] · required

Enum values:

shipment.created

shipment.in_transit

shipment.delivered

shipment.exception

id

string · uuid · readOnly

active

boolean

Default: true

createdAt

string · date-time · readOnly

secret

string · writeOnly

Secret used to sign webhook payloads. Generated via quantum key distribution; rotate from the developer portal if compromised.

POST

https://api.sh.example.com/v1

/webhooks

Registers a new webhook endpoint to receive shipment updates.

A secret will be generated and returned in the response. This secret should be used to verify the authenticity of webhook payloads.

Register a new webhook › Request Body

Webhook

url

string · uri · required

The URL where webhook events will be sent

events

string[] · required

Enum values:

shipment.created

shipment.in_transit

shipment.delivered

shipment.exception

id

string · uuid · readOnly

active

boolean

Default: true

createdAt

string · date-time · readOnly

secret

string · writeOnly

Secret used to sign webhook payloads. Generated via quantum key distribution; rotate from the developer portal if compromised.

Register a new webhook › Responses

Webhook registered successfully

Webhook

url

string · uri · required

The URL where webhook events will be sent

events

string[] · required

Enum values:

shipment.created

shipment.in_transit

shipment.delivered

shipment.exception

id

string · uuid · readOnly

active

boolean

Default: true

createdAt

string · date-time · readOnly

secret

string · writeOnly

Secret used to sign webhook payloads. Generated via quantum key distribution; rotate from the developer portal if compromised.