Webhooks and events - O.J. ADK

Every change to a referral creates an event. There are three ways to receive events:

Method	Use it for
Webhooks	Updating your system of record. Signed and retried for 72 hours.
Streaming	Live UIs and agents. `GET /referrals/{id}/events:stream` (SSE) resumes with `Last-Event-ID`.
Polling	Clients that can’t receive webhooks. `GET /events` returns the last 30 days, in order.

To get events for a single referral, register a per-referral webhook with its own token and expiry (POST /referrals/{id}/webhooks).

Verify signatures

Deliveries follow Standard Webhooks. Each one carries webhook-id, webhook-timestamp and webhook-signature headers. Verify them with the secret returned when you registered the endpoint.

import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.OJ_WEBHOOK_SECRET);

app.post("/webhooks/oj", express.raw({ type: "*/*" }), (req, res) => {
  const event = wh.verify(req.body, req.headers);
  if (event.type === "offer.received") notifyTeam(event.referral_id, event.data);
  res.sendStatus(204);
});

from standardwebhooks import Webhook

wh = Webhook(os.environ["OJ_WEBHOOK_SECRET"])

@app.post("/webhooks/oj")
def oj_webhook():
    event = wh.verify(request.get_data(), request.headers)
    if event["type"] == "referral.funded":
        mark_funded(event["referral_id"], event["data"])
    return "", 204

use StandardWebhooks\Webhook;

$wh = new Webhook(env('OJ_WEBHOOK_SECRET'));
$event = $wh->verify($request->getContent(), $request->headers->all());
if ($event['type'] === 'payout.updated') {
    PartnerLedger::sync($event['referral_id'], $event['data']);
}
return response()->noContent();

Retries reuse the same webhook-id, so deduplicate on it.

Event types

Event	Fires when
`referral.received`	O.J. accepted the referral
`referral.matches_updated`	The lenders the business matches changed
`referral.needs_partner`	Your team needs to act (see `data.todos`)
`referral.needs_borrower`	The borrower needs to act (see `data.todos`)
`referral.reminder_due`	A next action is overdue and O.J. has no channel to send a reminder
`document_request.opened`	A document was requested
`document_request.satisfied`	A requested document was received
`referral.submitted`	The file was sent to lenders
`offer.received`	A lender made an offer
`offer.accepted`	The borrower accepted an offer
`referral.funded`	The loan funded
`referral.declined`	A lender declined (`data.outcome` names it)
`referral.closed`	The referral ended without a lender decision, for example no match
`message.sent`	O.J. sent a message (`data` is the Message)
`message.received`	The borrower or your team sent a message
`submission.awaiting_review`	A submission is ready for your program’s reviewer
`submission.decided`	A decision was recorded on a submission
`payout.updated`	A payout changed status