Skip to main content
Routeur posts a signed JSON event to your HTTPS endpoint when a graph run finds a lead that could be filled at a profit against both venues’ live order books. Each delivery is signed with a secret that belongs to your subscription and is retried until your endpoint acknowledges it. Subscriptions are created by the Routeur team today; there is no self-serve endpoint.

What fires

Only executable leads raise alerts. Each graph run prices every proven relation from top-of-book asks, then walks the live books for the best leads by estimated edge. A lead is queued only when depth.executable is true, so:
  • Informational leads never fire. A lead whose relation rests on a settlement the venues could resolve differently (economic releases that are delayed or cancelled) is reported with depth.limited_by: informational and depth.executable: false in the API, and is never delivered as a webhook.
  • Leads whose fill is stopped by an order minimum, by fee rounding, or by an unreadable order book are not delivered either.
  • In a delivered event, depth.limited_by is therefore always price or depth. The other values appear only on GET /v1/opportunities.
An unchanged lead is not re-sent to the same subscription for six hours unless its net profit at least doubles compared with every delivery of that lead in the window. A lead is identified by both markets, the versions of their rules, and the two sides bought, so a rules change on either market makes it a new lead.

Cadence

Alerts are queued at the end of each graph run, which builds hourly (see Freshness). A separate delivery job drains the queue every two minutes, so a lead reaches your endpoint within about two minutes of the run that found it, plus any retries. Up to four deliveries are in flight at once, so two events from the same run can arrive in either order; use created_at and graph_run rather than arrival order.

Filters

Every subscription carries the settings below. They are fixed when the subscription is created; ask the Routeur team for a new subscription to change them.

JSON and Slack formats

json delivers the event bodies documented on the lead.executable and ping pages, with the headers below. slack is for a Slack incoming webhook URL. The body is {"text": "..."}, formatted for Slack’s markup, and no JSON event is sent. The example lead on the lead.executable page renders as:
A ping to a Slack subscription posts Routeur alerts are connected. Executable mispricings will be posted here. Slack deliveries carry the same signature headers, computed over the Slack body; Slack ignores them.

Getting a subscription

Subscriptions are created by the Routeur team, not through the API. Send them:
  1. the API key the subscription belongs to (its id, never the secret);
  2. your HTTPS endpoint, or a Slack incoming webhook URL;
  3. the format, minimum net and cross-venue setting you want.
You get back a subscription id, sub_ followed by 16 lowercase letters and digits, and a signing secret, whsec_ followed by 64 hex characters. The secret is shown once and is not stored by Routeur: it is derived from a master secret and your subscription id when needed. Store it server-side and use the whole string, prefix included, as the HMAC key (see Verifying signatures). If the master secret is rotated, every subscriber gets a new secret from the Routeur team. Alerts are queued only while the key that owns the subscription is active. Revoking the key stops new alerts.

Endpoint requirements

The URL is checked when the subscription is created, and the address is checked again each time a connection is made.

Delivery

Each delivery is one POST with these headers: Routeur waits 5 seconds to connect, 8 seconds for your response headers and 10 seconds in total. Respond with any 2xx first and do slow work afterwards. Response bodies are ignored. The body is sent as stored in Routeur’s outbox. Do not depend on key order or whitespace; the examples on these pages are formatted for reading. Verify signatures over the exact bytes received.

Retries

A failed delivery is retried up to 8 attempts in total, with the wait doubling from 30 seconds: 30 s, 1 min, 2 min, 4 min, 8 min, 16 min and 32 min after each failure. Because the delivery job runs every two minutes, an attempt happens at the first run after its wait has passed. After the eighth failure the event is marked failed and is not sent again. Routeur-Delivery stays the same across retries, so store the ids you have handled and ignore a repeat. Routeur-Signature is computed fresh on each attempt, so its t reflects the attempt, not the first send.

Disabling a subscription

  • Respond 410 Gone to any delivery, and the subscription is disabled on the spot.
  • Ask the Routeur team to disable it.
A disabled subscription is never re-enabled; queued deliveries for it are dropped, and you need a new subscription (with a new secret) to receive alerts again.