Webhooks Documentation
Receive automatic real-time alerts whenever key events happen in your Orenyx AI workspace, without manual dashboard checking.
How Webhooks Work (Simple Analogy)
Instead of calling a company every hour to ask "Do you have an update for me?" (Polling), you leave your phone number with them and ask "Text me immediately when it's ready" (Webhooks).
[ Event Occurs in Orenyx AI ] ──( Instant Notification )──> [ Your Server / Zapier / Slack ]
Example: New Lead Captured Adds row to Google Sheets or alerts teamStep-by-Step Setup Guide
For Non-Technical Users (Using Zapier or Make.com)
- Open Zapier and create a new Zap.
- Choose "Webhooks by Zapier" as your Trigger app, and select "Catch Hook".
- Zapier will generate a custom Webhook URL (e.g. https://hooks.zapier.com/hooks/catch/...). Copy it.
- In Orenyx AI, navigate to Developer → Webhooks and click "Add Endpoint".
- Paste your Zapier URL into the endpoint field and click Save.
- Click "Send Test" to verify data arrives instantly in your Zapier test step.
For Developers (Custom Webhook Listener Server)
- Expose a public HTTP POST endpoint on your server (e.g. https://api.yourdomain.com/webhooks/orenyx).
- Register your URL in Developer → Webhooks in the Orenyx AI portal.
- Copy your unique raw-hex Signing Secret generated upon endpoint creation (e.g. 64-character hex string).
Supported Event Types
| Event Name | Triggers When | Payload Data Included |
|---|---|---|
| lead.created | A new B2B lead is captured and ingested. | Lead ID, Name, Email, Company, Source |
| ledger.entry_recorded | A new financial transaction or fee is recorded on the ledger. | Entry ID, Amount, Currency, Category |
| settlement.reconciled | A settlement reconciliation batch successfully completes. | Settlement ID, Reconciled Amount, Status |
| settlement.retry_attempted | A failed settlement reconciliation attempt is retried. | Settlement ID, Attempt Count, Last Error |
Security & Signature Verification (For Developers)
Every webhook notification sent by Orenyx AI includes HTTP headers for security and verification, and a body containing the delivery's own id, the event name, the payload, and the timestamp it was sent:
x-orenyx-signature: HMAC-SHA256 hash of{timestamp}.{payload}, calculated with your webhook secret.x-orenyx-timestamp: The Unix timestamp (seconds) the request was sent. Used both to compute the signature and to detect a stale, replayed request.x-orenyx-event: The specific event identifier (e.g.lead.created).- Request body:
{ id, event, payload, timestamp }.idstays the same across retries of the same delivery, so you can tell "the same event, retried" apart from "a genuinely new event."
Node.js / Express Verification Example
const crypto = require('crypto');
function verifyOrenyxWebhook(req, secret, { toleranceSeconds = 300 } = {}) {
const signature = req.headers['x-orenyx-signature'];
const timestamp = Number(req.headers['x-orenyx-timestamp']);
// Reject a request whose timestamp is missing, malformed, or too old.
// This is what stops a captured, valid request from being replayed later.
if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) {
return false;
}
const signedContent = `${timestamp}.${JSON.stringify(req.body.payload)}`;
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(signedContent)
.digest('hex');
const sigBuf = Buffer.from(signature || '', 'hex');
const expectedBuf = Buffer.from(expectedSignature, 'hex');
if (sigBuf.length !== expectedBuf.length) return false;
return crypto.timingSafeEqual(sigBuf, expectedBuf);
}
// Separately, track req.body.id (the delivery id) in your own database and
// skip processing if you've already handled that id. This covers both a
// legitimate retry of the same delivery, and a resent/replayed request that
// still falls inside the timestamp tolerance window above.Endpoint requirements
A webhook URL you register must be a public https:// address. Plain http:// is rejected, and so is any address that resolves to a private, loopback, or link-local range (for example localhost, 127.0.0.1, 192.168.x.x, or a cloud metadata address). This protects both you and us: it stops a webhook URL from ever being used to make our servers reach into a private network they should never be able to touch.
Replay protection
Every delivery is signed together with the exact second it was sent (x-orenyx-timestamp), not just the payload on its own. If someone captures a genuine, correctly-signed request and resends it later, checking that timestamp against the current time (as in the verification example above) is what catches it, a resent request from more than a few minutes ago fails that check even though the signature itself is completely valid.
The delivery id in the body (stable across our own retries of the same delivery, but unique per real event) is what lets your endpoint tell a legitimate retry apart from a brand new event, so an action that must never happen twice, like crediting an account, only ever runs once per real event.
Managing & Monitoring Endpoints
- Send Test: Dispatches a mock payload immediately so you can test receiving logic.
- Rotate Secret: Replaces your signing secret instantly if exposed.
- Delivery History: Shows status (DELIVERED / FAILED), HTTP response code, and a 1-click "Retry" button.
Was this page helpful?