Ordexs API v1 Get an API key

Webhooks

Receiving webhooks

Ordexs posts an event to your URL the moment something changes in the store: an order created, confirmed, shipped or delivered, stock moved, a customer added.

How it works

  1. You register an endpoint: an HTTPS URL on your server, and the events it wants.
  2. When something changes, Ordexs sends a POST to that URL with an event as JSON, signed with the endpoint's secret.
  3. Your server checks the signature, answers 2xx quickly, and does the work afterwards.

Events are written in the same database transaction as the change itself. If the change is saved, the event will be sent; if it's rolled back, no event exists.

Creating an endpoint

In the dashboard: Settings → Developers → Webhooks → Add endpoint. Or with the API:

curl -X POST https://api.ordexs.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $ORDEXS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/ordexs",
    "events": ["order.created", "order.status_changed"],
    "description": "Order sync"
  }'

The response includes the endpoint's signing secret (whsec_…). It is shown once: store it with your other secrets. A live key creates live endpoints and a test key creates test endpoints; each only receives events from its own mode.

The URL must be https:// on port 443 or 8443, on a public host. Addresses that resolve to private, local or reserved networks are refused, and so are Ordexs's own domains. The number of endpoints depends on the plan: 2 on Starter, 5 on Growth, 20 on Scale.

Subscribe only to the events you handle; the full list is on the events page. ["*"] subscribes to everything, including event types added later, so only use it if your handler ignores types it doesn't know.

What you receive

POST /webhooks/ordexs HTTP/1.1
Content-Type: application/json
User-Agent: Ordexs-Webhooks/1.0 (+https://ordexs.com/docs/webhooks)
Ordexs-Signature: t=1760177100,v1=5f2b…
Ordexs-Event-Id: evt_1a2b3c4d5e6f40718293a4b5c6d7e8f9
Ordexs-Event-Type: order.status_changed
Ordexs-Delivery-Id: 7c1e…
Ordexs-Delivery-Attempt: 1

The body is the event object: its type, and in data.object the full object exactly as the API would return it at that moment. For updates, data.previous_attributes has the fields that changed and their old values. You don't need to call the API back to see what happened.

Answering

  • Answer with any 2xx status within 10 seconds. The body of your answer is ignored.
  • Do the real work after answering, in a queue or a background job. A slow handler times out and gets the same event again.
  • Redirects are not followed: a 3xx counts as a failure. Point the endpoint at the final URL.

Retries

Anything other than a 2xx in time is retried, with growing gaps: after about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours, then every 12 hours, for 3 days. After that the delivery is given up, and it can still be resent by hand from the delivery log in the dashboard.

If an endpoint has failed for 3 days with no success at all, Ordexs turns it off and tells the store owner by email and in the dashboard. Turn it back on in the dashboard once your server is fixed.

Duplicates and order

Delivery is at least once: the same event can arrive twice, for example when your server saved it but answered too late. Remember the id of every event you processed (it's also in the Ordexs-Event-Id header) and skip ids you've seen.

Delivery order is not guaranteed. A order.status_changed to delivered can arrive before the one to shipped. Compare data.object.updated_at with what you stored, and ignore an event older than your copy.

Missed something?

GET /v1/events lists every event of the last 30 days, newest first, with the same payloads. Use it to catch up after downtime, or reconcile once a day as a safety net.

Testing

  • Send test event in the dashboard, or POST /v1/webhook_endpoints/{id}/test, sends a ping to the endpoint.
  • Test endpoints receive the events your test-key calls cause. See Test mode.
  • The dashboard's delivery log shows every attempt: status, response code, timing and payload, kept 7 days on Starter, 14 on Growth and 30 on Scale.

Rotating the secret

POST /v1/webhook_endpoints/{id}/rotate_secret (or Rotate secret in the dashboard) issues a new secret. For the overlap you choose, 24 hours by default and up to 72, every delivery is signed with both the new and the old secret, so you can deploy the new one without missing an event. An overlap of 0 retires the old secret at once.