Webhooks and the wider API
The 1.9.0 API routes (own listings, offers, orders, portfolio, membership, webhooks, events, reviews), the API Monitor, and webhooks: endpoints and events, the signed delivery and how to verify it, retries, switch-off, re-send.
1. The API in 1.9.0
Chapter The REST API explains keys, the Authorization header, scopes and the public routes. 1.9.0 adds routes for a member's own data; the live list, with the scope each one needs, is always at GET /api/v1 and on the site's API docs page.
| Route | Scope | What it does |
|---|---|---|
GET listings | listings | my listings with status, views, usage against the plan limit |
POST listing-create | listings | a new listing (name, listing_type, price, min_offer, title, description, category_id, tags, submit) |
POST listing-update/<id> | listings | price, texts, tags, category of my listing |
POST listing-status/<id> | listings | action=pause, resume or submit |
GET offers?side= | trade | my offers as buyer or seller |
GET orders?side= | trade | my orders as buyer or seller |
GET portfolio | portfolio | my portfolio (filters status, registrar, q) |
POST portfolio-add | portfolio | a domain into my portfolio |
POST portfolio-sync | portfolio | sync a connected registrar account now |
GET membership | profile | my plan, its features, the listing usage |
GET webhooks, POST webhook-create, POST webhook-delete/<id>, POST webhook-ping/<id> | webhooks | my endpoints |
GET events | public | the webhook event types and the signature recipe |
GET reviews?user= | public | a member's published reviews and rating |
Bodies may be form fields or JSON. A plan may raise the key's calls per minute (feature API calls per minute). Staff watch the API under Developers -> API Monitor: calls, errors, error rate, average response time, keys in use, rate-limited calls, the busiest routes, the top errors and the request log with filters.
2. Webhooks
A member registers endpoints under API Keys -> Webhooks (or through the API): an https address, a description, and the events to receive (listings approved / rejected / expired / sold, ownership verified, offers, orders, transfers, auctions, inquiries, membership, portfolio expiry, reviews, and ping for tests). The secret is shown once when the endpoint is made and can be rotated.
A delivery is a JSON POST:
POST <your url>
Content-Type: application/json
X-AIOD-Event: order.paid
X-AIOD-Delivery: evt_5f3c… (unique per delivery; use it to ignore repeats)
X-AIOD-Timestamp: 1762128000
X-AIOD-Signature: sha256=<hex>
{"id":"evt_5f3c…","event":"order.paid","created_at":"2026-11-03T01:00:00+00:00","site":"https://…","data":{…}}
The signature is HMAC-SHA256(secret, timestamp + "." + raw body). Verify it, and refuse timestamps older than five minutes:
$body = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_AIOD_TIMESTAMP']; $sig = $_SERVER['HTTP_X_AIOD_SIGNATURE'];
$ok = hash_equals('sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret), $sig) && abs(time() - (int) $ts) < 300;
Answer with any 2xx status within the timeout (default 10 s). Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours; after the last attempt the delivery is marked failed. An endpoint that fails 20 times in a row (setting) is switched off and the member is told by mail; fixing the address and switching it on resets the count, and every delivery can be re-sent from its row. Payloads carry ids and public facts only, never credentials.
Addresses must be https on a public host; private networks and localhost are refused (two dev-only settings allow http and private addresses for testing). Staff see every endpoint under Developers -> Webhooks (tabs all / failing / off, the deliveries, re-send, switch off or on). Settings -> Security -> Webhooks: on / off, endpoints per member on the free plan, timeout, failures before switch-off, how long deliveries are kept.