Webhook API

Webhooks

Endpoint

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

object[]

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

GET/webhooks

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

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

const webhooks = await client.listWebhooks();

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"
  }
]

json

application/json

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

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

Register a new webhook › Responses

Webhook registered successfully

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

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

object[]

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

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

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

Register a new webhook › Responses

Webhook registered successfully

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

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], });

{ "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" }