Skip to content
RUBI

Webhooks

Rubi calls your endpoint when interviews move. Every delivery is signed and retried; legacy integration event types remain in the catalog.

Verify your endpoint before creating a secret#

Deploy your HTTPS receiver first, then enter its URL in Developers → Webhooks. Choose Check endpoint to test it, or Verify and create to check and save it. Rubi sends an unsigned setup challenge to your backend before creating the webhook or generating its signing secret.

Verification request sent to your URL
{
  "type": "webhook.endpoint_verification",
  "challenge": "an-unpredictable-value-generated-by-rubi"
}

Return a successful 2xx response containing the same challenge in JSON. The Node.js and Python examples below handle this setup request before signature verification.

Required verification response
{
  "challenge": "an-unpredictable-value-generated-by-rubi"
}

When verification succeeds, Rubi creates the endpoint and shows its secret once. Store that secret in your receiver, then send a test event to confirm signature handling and delivery. If the URL is unreachable, returns an error, redirects, or does not echo the challenge, creation fails with 422 and errors.url; no endpoint or secret is created. Changing the URL requires a new verification. Passing the check confirms that the receiver is reachable and implements the handshake; signed event processing still needs the test delivery.

Accept only the challenge response without a signature. All interview, integration and ping events must pass signature verification before they change anything in your system.

Events#

TypeWhendata
interview.createdAn interview and its invite link were created.{ interview }
interview.startedThe trader started recording.{ interview }
interview.submittedThe trader finished.{ interview }
interview.report_readyThe AI report is ready for review.{ interview }
interview.decidedAn analyst recorded a decision.{ interview, decision }
integration.sync_succeededLegacy global sync event. On-demand retrieval does not emit this event.{ integration_id, resource, error }
integration.sync_failedLegacy global sync event. On-demand retrieval does not emit this event.{ integration_id, resource, error }
pingSent by the test button or the test endpoint.{}

interview is an event snapshot containing at least id and status. Additional fields depend on the event; interview.report_ready includes risk_score and recommended_step. Fetch GET /v1/interviews/{id} for the complete, current interview.

Delivery#

Each delivery is a POST with a JSON body:

json
{
  "id": "evt_4c7e1d2a-9b0f-4f7e-8a51-0d2c6b3e9f10",
  "type": "interview.report_ready",
  "created_at": "2026-09-23T10:00:00Z",
  "organization_id": "0b8e...",
  "data": { "interview": { "id": "8f0b1c52-...", "status": "report_ready", "risk_score": "medium" } }
}
HeaderValue
Rubi-EventThe event type.
Rubi-DeliveryA uuid, unique per delivery attempt group. Use it to deduplicate.
Rubi-Signaturet=<unix>,v1=<hex>

Verifying signatures#

v1 is HMAC_SHA256(secret, "<t>.<raw body>") in hex, where the key is your full signing secret including the whsec_ prefix. Always compute it over the raw bytes, before any JSON parsing, compare in constant time and reject old timestamps.

node
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.RUBI_WEBHOOK_SECRET; // whsec_...
const TOLERANCE_S = 300;

app.post("/webhooks/rubi", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try { event = JSON.parse(req.body.toString("utf8")); }
  catch { return res.sendStatus(400); }
  if (!event || typeof event !== "object" || Array.isArray(event)) return res.sendStatus(400);
  // This setup challenge is unsigned and must never trigger business actions.
  if (event?.type === "webhook.endpoint_verification") {
    if (typeof event.challenge !== "string" || event.challenge.length > 128) return res.sendStatus(400);
    return res.json({ challenge: event.challenge });
  }
  if (!SECRET) return res.sendStatus(503);
  const header = req.get("Rubi-Signature") ?? "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!Number.isSafeInteger(t) || t <= 0 || Math.abs(Date.now() / 1000 - t) > TOLERANCE_S) return res.sendStatus(400);
  if (!/^[a-fA-F0-9]{64}$/.test(parts.v1 ?? "")) return res.sendStatus(400);

  const expected = crypto.createHmac("sha256", SECRET).update(`${t}.${req.body}`).digest("hex");
  const given = Buffer.from(parts.v1 ?? "", "hex");
  const valid = given.length === 32 && crypto.timingSafeEqual(given, Buffer.from(expected, "hex"));
  if (!valid) return res.sendStatus(400);

  if (event.type === "interview.report_ready") {
    // enqueue your own processing, then answer fast
  }
  res.sendStatus(200);
});

Retries#

Answer with any 2xx within a few seconds. Otherwise Rubi retries with exponential backoff: after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours. Every attempt is visible in the dashboard under Developers, with the status code and response body, and can be retried by hand.

Deliveries can arrive more than once or out of order. Deduplicate on the event id and read the latest state from the API when order matters.

Managing endpoints#

Endpoints can be managed from the dashboard or with a key holding webhooks:manage. Secrets are shown once, on creation and rotation.

GET/v1/webhookswebhooks:manage

Returns { data: WebhookEndpoint[] }

GET/v1/webhooks/eventswebhooks:manage

Returns { data: { type, description }[] }

POST/v1/webhooks/checkwebhooks:manage

Returns { ok: true, url, verified_at }

Body { "url": "https://hooks.yourfirm.com/rubi" }. Checks the receiver without saving an endpoint or generating a secret.

POST/v1/webhookswebhooks:manage

Returns WebhookCreated

Body { "url": "https://...", "events": ["interview.report_ready"] }. Rechecks the endpoint, then generates and returns its secret on success.

PATCH/v1/webhooks/{id}webhooks:manage

Returns WebhookEndpoint

Update url, events or is_active. A changed URL, or activation of an endpoint that has never been verified, must pass the challenge first.

DELETE/v1/webhooks/{id}webhooks:manage

POST/v1/webhooks/{id}/testwebhooks:manage

Returns WebhookDelivery

POST/v1/webhooks/{id}/rotate-secretwebhooks:manage

Returns WebhookCreated

GET/v1/webhooks/{id}/deliverieswebhooks:manage

Returns Page<WebhookDelivery>

POST/v1/webhooks/deliveries/{deliveryId}/retrywebhooks:manage

Returns WebhookDelivery