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
- Failed deliveries are retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h (8 attempts in total). You can also retry any delivery from the log.
- An endpoint that fails 20 deliveries in a row (each after all its attempts) is disabled automatically; re-enable it in the console after fixing it.
- Events can arrive more than once and out of order. De-duplicate on
id; usecreatedand the approval's status, not arrival order. - The first attempt is usually sent within a second. Delivery logs are kept for 30 days.
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.