Event push

Your system can tell OrgRelay when something happens: a new order, stock below the safety level, an escalated ticket. OrgRelay alerts the owner in the chat apps they use and lists the event among its alerts.

Events are optional. A read-only connector without events is perfectly valid. Add them when "tell me when..." is something your users ask for. Declare the types you push in the manifest under events.

#Getting the push URL and secret

After the owner binds your connector, OrgRelay shows:

• a push URL, https://<company OrgRelay>/hooks/connector/<random>, and
• a secret, shown once. The owner can regenerate it.

The owner hands both to you. Store the secret like any other credential (see authentication).

#The payload

POST JSON to the push URL. The format is spec/event.schema.json in the developer kit.

{
  "id": "evt_8f3a2c",
  "type": "inventory.low_stock",
  "occurred_at": "2026-11-09T10:00:00+08:00",
  "summary": "HX-330 stock 95, below safety stock 150",
  "data": { "sku": "HX-330", "on_hand": 95 }
}

#Signing

Every request carries one header:

X-OrgRelay-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + "." + raw body)>

Sign the raw body bytes you send, not a re-serialised object. OrgRelay rejects signatures more than five minutes from its clock, which blocks replays.

import crypto from 'node:crypto';
const body = JSON.stringify(event);
const t = Math.floor(Date.now() / 1000);
const v1 = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
await fetch(pushUrl, { method: 'POST', body,
  headers: { 'Content-Type': 'application/json', 'X-OrgRelay-Signature': `t=${t},v1=${v1}` } });

import hmac, hashlib, json, time, urllib.request
body = json.dumps(event, separators=(",", ":")).encode()
t = str(int(time.time()))
v1 = hmac.new(secret.encode(), (t + ".").encode() + body, hashlib.sha256).hexdigest()
req = urllib.request.Request(push_url, data=body, method="POST",
    headers={"Content-Type": "application/json", "X-OrgRelay-Signature": f"t={t},v1={v1}"})
urllib.request.urlopen(req, timeout=10)

$body = json_encode($event, JSON_UNESCAPED_UNICODE);
$t = time();
$v1 = hash_hmac('sha256', $t . '.' . $body, $secret);
$ch = curl_init($pushUrl);
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_POSTFIELDS => $body, CURLOPT_TIMEOUT => 10,
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', "X-OrgRelay-Signature: t=$t,v1=$v1"]]);
curl_exec($ch);

To check your signing against a known value, the self-test tool has a helper:

node bin/orgrelay-connector-check.mjs sign-event --secret <secret> --file event.json

#Delivery and retries

• Only a 2xx response means delivered.
• On any other status, or no answer within 10 seconds, retry after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours: six attempts in total, all with the same id.
• OrgRelay answers a duplicate id with 200 { "duplicate": true }.
• Do not retry 400, 404 or 410. They mean the payload is wrong or the push URL no longer exists.

#Suggested event types

Names follow the domains on standard tools, so OrgRelay can route an event to the department agent that owns it.

#What the owner sees

The summary arrives in the owner's chat app of choice, such as WhatsApp, Telegram or WeCom, and also appears among OrgRelay's alerts. How alerts work for the business, and how owners tune them, is described on orgrelay.com's alerts page.

#Common questions

Required? No.

summary versus data? summary is a safe sentence for chat. data carries ids.

Test signature? orgrelay-connector-check sign-event.

#Next

• Security requirements, especially what may appear in summary.
• Approvals and write tools: events are a good way to report the outcome of long-running writes.
• Templates: all four templates include a signed push function you can copy; the Node.js, Python and Java versions re-sign every retry.
• In sandbox mode the owner can watch events arrive, as described in the quickstart.
• Platforms whose connectors pair well with events: WooCommerce orders and Stripe payments.
• Authentication for the calls OrgRelay makes back to you after an event: authentication.
• The connector side of the contract: connector spec.
• Staff can ask about events from their AI client too: MCP overview and Claude Code.

#Related pages

• MCP transport: serve a connector over Streamable HTTP.
• Enterprise patterns: permissions, offboarding and data residency.
• Human-in-the-loop: why approvals live outside the AI client.
• OpenAPI import: turn an OpenAPI or Swagger file into tools.
• Third-party MCP: put a vendor's MCP server behind OrgRelay.
• Codex: config.toml with the token in an environment variable.