RegisterWebhook

curl --request POST \
  --url https://api.worldmonitor.app/api/v2/shipping/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-WorldMonitor-Key: <api-key>' \
  --data '
{
  "alertThreshold": 1,
  "callbackUrl": "https://example.com/worldmonitor-webhook",
  "chokepointIds": [
    "suez"
  ]
}
'

import requests

url = "https://api.worldmonitor.app/api/v2/shipping/webhooks"

payload = {
    "alertThreshold": 1,
    "callbackUrl": "https://example.com/worldmonitor-webhook",
    "chokepointIds": ["suez"]
}
headers = {
    "X-WorldMonitor-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-WorldMonitor-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    alertThreshold: 1,
    callbackUrl: 'https://example.com/worldmonitor-webhook',
    chokepointIds: ['suez']
  })
};

fetch('https://api.worldmonitor.app/api/v2/shipping/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.worldmonitor.app/api/v2/shipping/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'alertThreshold' => 1,
    'callbackUrl' => 'https://example.com/worldmonitor-webhook',
    'chokepointIds' => [
        'suez'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-WorldMonitor-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.worldmonitor.app/api/v2/shipping/webhooks"

	payload := strings.NewReader("{\n  \"alertThreshold\": 1,\n  \"callbackUrl\": \"https://example.com/worldmonitor-webhook\",\n  \"chokepointIds\": [\n    \"suez\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-WorldMonitor-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.worldmonitor.app/api/v2/shipping/webhooks")
  .header("X-WorldMonitor-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"alertThreshold\": 1,\n  \"callbackUrl\": \"https://example.com/worldmonitor-webhook\",\n  \"chokepointIds\": [\n    \"suez\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.worldmonitor.app/api/v2/shipping/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-WorldMonitor-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"alertThreshold\": 1,\n  \"callbackUrl\": \"https://example.com/worldmonitor-webhook\",\n  \"chokepointIds\": [\n    \"suez\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "secret": "example",
  "subscriberId": "example-id"
}

{
  "violations": [
    {
      "field": "<string>",
      "description": "<string>"
    }
  ]
}

{
  "error": "<string>"
}

{
  "error": "<string>",
  "code": "subscription_lapsed",
  "requiredTier": 123,
  "currentTier": 123,
  "planKey": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "error": "<string>",
  "code": "renewal_verification_pending",
  "requiredTier": 123
}

{
  "message": "<string>"
}

POST

api

shipping

webhooks

RegisterWebhook

curl --request POST \
  --url https://api.worldmonitor.app/api/v2/shipping/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-WorldMonitor-Key: <api-key>' \
  --data '
{
  "alertThreshold": 1,
  "callbackUrl": "https://example.com/worldmonitor-webhook",
  "chokepointIds": [
    "suez"
  ]
}
'

import requests

url = "https://api.worldmonitor.app/api/v2/shipping/webhooks"

payload = {
    "alertThreshold": 1,
    "callbackUrl": "https://example.com/worldmonitor-webhook",
    "chokepointIds": ["suez"]
}
headers = {
    "X-WorldMonitor-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-WorldMonitor-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    alertThreshold: 1,
    callbackUrl: 'https://example.com/worldmonitor-webhook',
    chokepointIds: ['suez']
  })
};

fetch('https://api.worldmonitor.app/api/v2/shipping/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.worldmonitor.app/api/v2/shipping/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'alertThreshold' => 1,
    'callbackUrl' => 'https://example.com/worldmonitor-webhook',
    'chokepointIds' => [
        'suez'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-WorldMonitor-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.worldmonitor.app/api/v2/shipping/webhooks"

	payload := strings.NewReader("{\n  \"alertThreshold\": 1,\n  \"callbackUrl\": \"https://example.com/worldmonitor-webhook\",\n  \"chokepointIds\": [\n    \"suez\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-WorldMonitor-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.worldmonitor.app/api/v2/shipping/webhooks")
  .header("X-WorldMonitor-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"alertThreshold\": 1,\n  \"callbackUrl\": \"https://example.com/worldmonitor-webhook\",\n  \"chokepointIds\": [\n    \"suez\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.worldmonitor.app/api/v2/shipping/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-WorldMonitor-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"alertThreshold\": 1,\n  \"callbackUrl\": \"https://example.com/worldmonitor-webhook\",\n  \"chokepointIds\": [\n    \"suez\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "secret": "example",
  "subscriberId": "example-id"
}

{
  "violations": [
    {
      "field": "<string>",
      "description": "<string>"
    }
  ]
}

{
  "error": "<string>"
}

{
  "error": "<string>",
  "code": "subscription_lapsed",
  "requiredTier": 123,
  "currentTier": 123,
  "planKey": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "error": "<string>",
  "code": "renewal_verification_pending",
  "requiredTier": 123
}

{
  "message": "<string>"
}

Authorizations

X-WorldMonitor-Key

string

header

required

User-issued WorldMonitor API key.

Headers

Idempotency-Key

string

Optional client-generated idempotency key. Retrying a POST with the same key and an identical request body replays the original response (only the status, body, and Content-Type are reproduced) instead of re-executing; reusing the key with a different body is rejected with 422. For mutations this avoids duplicating the side effect, while for batch-read POSTs it replays a cached snapshot that can be up to 24 hours stale. Keys are scoped per authenticated caller (falling back to the source IP for unauthenticated endpoints) and retained for 24 hours.

Required string length: 1 - 255

Pattern: ^[\x21-\x7E]{1,255}$

Body

application/json

RegisterWebhookRequest creates a new chokepoint-disruption webhook subscription. Wire shape is byte-compatible with the pre-migration legacy POST body.

callbackUrl

string

required

HTTPS callback URL. Must not resolve to a private/loopback address at registration time (SSRF guard). The delivery worker re-validates the resolved IP before each send to mitigate DNS rebinding.

Required string length: 8 - 2048

chokepointIds

string[]

Zero or more chokepoint IDs to subscribe to. Empty list subscribes to the entire CHOKEPOINT_REGISTRY. Unknown IDs fail with 400.

alertThreshold

integer<int32>

Disruption-score threshold for delivery, 0-100. Default 50. proto3 optional so the handler can distinguish "partner explicitly sent 0 (deliver every alert)" from "partner omitted the field (apply default 50)". Without optional, both serialise to the proto3 scalar default of 0 and the handler can't tell them apart — flagged in #3242 review.

Required range: 0 <= x <= 100

Response

Successful response

RegisterWebhookResponse wire shape preserved exactly — partners persist the secret because the server never returns it again except via rotate-secret.

subscriberId

string

wh_ prefix + 24 lowercase hex chars (12 random bytes).

secret

string

Raw 64-char lowercase hex secret (32 random bytes). No whsec_ prefix.