Webhooks

Instead of polling, Trowyn can POST signed events to your server.

Console → Webhooks → Add endpoint (per environment). Choose the events, or leave all selected. The signing secret (whsec_…) is shown once; you can rotate it later. Use Send test event to try your handler, and the delivery log to see every attempt, its HTTP status and the response error.

Events

Type When data
approval.approved User approved on the phone approval_id, external_user_id, status, deny_reason, app_name, created_at, expires_at, decided_at
approval.denied User denied, or picked the wrong number (deny_reason) same
approval.expired Nobody answered before expires_at (sent within ~15 s) same
device.linked A phone redeemed one of your link codes link_id, external_user_id, label, linked_at
device.unlinked The user unlinked in Trowyn, or you unlinked in the console link_id, external_user_id, label, unlinked_at, unlinked_by (device / company)
{
  "id": "evt_3f779ccd08124be2b7ba2f6e2f616831",
  "object": "event",
  "type": "approval.approved",
  "created": 1794951154,
  "environment": "live",
  "org_id": "d67beab9-…",
  "test_event": false,
  "data": { "approval_id": "6b899e9b-…", "external_user_id": "user-42", "status": "approved", "deny_reason": null,
            "app_name": "Acme Portal", "created_at": "…", "expires_at": "…", "decided_at": "…" }
}

test_event: true marks events sent with Send test event: they use made-up ids.

Request

POST to your HTTPS URL with Content-Type: application/json and these headers:

Header
Trowyn-Signature t=<unix seconds>,v1=<hex HMAC-SHA256>
Trowyn-Event-Id Same as the body's id. Use it to de-duplicate
Trowyn-Event-Type e.g. approval.approved
Trowyn-Delivery-Id, Trowyn-Delivery-Attempt For support and logging
User-Agent Trowyn-Webhooks/1.0 (+https://trowyn.com/docs/webhooks/) …

Respond with any 2xx within 10 seconds. Anything else (including redirects) counts as a failure. Do slow work after responding.

Verify the signature

v1 is HMAC-SHA256, keyed with your endpoint secret, over "<t>.<raw request body>". Use the raw bytes you received (not re-serialized JSON), compare in constant time, and reject timestamps more than 5 minutes old.

import { verifyWebhook } from "@trowyn/server";
const event = await verifyWebhook(rawBody, req.headers["trowyn-signature"], process.env.TROWYN_WEBHOOK_SECRET);

Without the SDK (Node):

import crypto from "node:crypto";
function verify(raw, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${raw}`).digest("hex");
  return parts.v1?.length === expected.length && crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Python:

import hmac, hashlib, time
def verify(raw: bytes, header: str, secret: str) -> bool:
    parts = dict(p.strip().split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300: return False
    mac = hmac.new(secret.encode(), parts["t"].encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, parts.get("v1", ""))

Retries and ordering

Endpoint rules

HTTPS on port 443 with a public hostname: no IP addresses, localhost, internal names (.local, .internal, …), credentials in the URL, or fragments. For local development use a tunnel (for example cloudflared or ngrok) and a test endpoint. Up to 5 endpoints per environment, each up to 500 characters.

Webhooks tell you what happened; they don't replace your sign-in check. Before letting a user in, make sure the event is for the approval that sign-in created (data.approval_id) and the right external_user_id. When in doubt, call approval-status.