Quickstart

Last updated October 20, 2026

Five steps from nothing to a verified key and a verified webhook. Steps 1 to 3 take about two minutes once you have a key in hand.

export BASE_URL="https://api.omnishelf.com"
export OMNI_KEY="omni_sk_YOUR_KEY"

---

Step 1 — Request an API key

Ask your Omnishelf contact for a Seller API key. You will receive a single string beginning with omni_sk_. It is shown to you exactly once — Omnishelf stores only a SHA-256 hash of it and cannot recover or re-display the original. Put it straight into your secret store.

# Keep the key in an environment variable, never in source control.
export BASE_URL="https://api.omnishelf.com"
export OMNI_KEY="omni_sk_YOUR_KEY"

---

Step 2 — Call GET /v1/ping

/v1/ping is the health and identity probe. It touches no order data, so it is the safe way to confirm a key is live before you wire anything else up.

curl -s "$BASE_URL/v1/ping" \
  -H "Authorization: Bearer $OMNI_KEY"

---

Step 3 — Check the response

A working key returns 200 with the API version and the webhook event types you can register. Read event_types from here rather than hard-coding it — the list grows without a version bump.

{
  "ok": true,
  "version": "v1",
  "event_types": [
    "fulfilment_order.created",
    "fulfilment_order.cancelled",
    "fulfilment_order.on_hold",
    "fulfilment_order.hold_released",
    "fulfilment_order.in_transit",
    "fulfilment_order.delivered",
    "fulfilment_order.undelivered",
    "fulfilment_order.status_changed"
  ]
}

The last five, from hold_released to status_changed, are order lifecycle events. You can register for them, but they are sent only once the order lifecycle is switched on for your account.

Every authenticated response also carries rate limit headers. Check them once here so you know what your client will be reading later:

curl -s -D - -o /dev/null "$BASE_URL/v1/ping" \
  -H "Authorization: Bearer $OMNI_KEY"

# HTTP/2 200
# x-ratelimit-limit: 100
# x-ratelimit-remaining: 99
# x-ratelimit-reset: 1786531260

---

Step 4 — Register a webhook callback URL

Send Omnishelf staff the HTTPS URL that should receive events and which event types you want. They register one webhook per event type and issue its signing secret, again shown once. Each webhook gets its own secret, and its deliveries verify only with that one. Your endpoint must accept a POST with a JSON body and answer within 10 seconds.

# What to send to your Omnishelf contact:
# callback_url: https://api.your-company.com/omnishelf/webhooks
# event_types: fulfilment_order.created, fulfilment_order.cancelled, fulfilment_order.on_hold

# What you get back:
# one signing secret per webhook — store each with the URL it signs for,
# e.g. OMNISHELF_WEBHOOK_SECRET for a single webhook

---

Step 5 — Receive and verify your first event

Ask Omnishelf staff to fire a test event at your endpoint. Verify the signature over the raw request body, acknowledge with 200, then process asynchronously.

import hmac, hashlib, os
from flask import Flask, request

app = Flask(__name__)
# The signing secret of the webhook registered for this URL (each webhook has its own).
SECRET = os.environ["OMNISHELF_WEBHOOK_SECRET"].encode()

@app.post("/omnishelf/webhooks")
def receive():
    raw = request.get_data()  # raw bytes, NOT request.json
    sent = request.headers.get("X-Omnishelf-Signature", "")
    expected = "sha256=" + hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sent, expected):
        return "", 401
    # Acknowledge first, process afterwards.
    enqueue(request.get_json())
    return "", 200

---

Next steps

• Read the Fulfilment Lifecycle before the endpoint reference — it explains why the endpoints are shaped the way they are.
• See Webhooks — Testing for a minimal local receiver you can expose with a tunnel.