Webhooks
Get notified when something happens in your account.
Add an endpoint in your dashboard, under Team → Webhooks, and Upsky will
POST events to it as they happen. Each endpoint is for test or live mode and
gets the events of that mode only.
{
"id": "6b2c9f3e-1a4d-4e5f-9b8a-7c6d5e4f3a2b",
"object": "event",
"type": "verify.session.approved",
"livemode": false,
"created_at": "2026-11-12T10:01:38Z",
"data": { "object": { "object": "verify.session", "id": "…", "status": "approved" } }
}Check the signature
Deliveries follow the Standard Webhooks
format, signed with your endpoint's secret (whsec_…). Each request carries
webhook-id, webhook-timestamp and webhook-signature headers. Check them
with any Standard Webhooks library before you trust the payload:
import { Webhook } from "standardwebhooks"
const event = new Webhook(process.env.UPSKY_WEBHOOK_SECRET).verify(
rawBody,
headers
)Respond quickly
Return a 2xx within 10 seconds and do slow work in the background. A failed
delivery is retried with backoff for up to two days, so the same event can
arrive more than once. Use id to ignore duplicates.
Events
| Event | Sent when |
|---|---|
verify.session.approved | A verification passed, or was approved in review |
verify.session.rejected | A verification failed, or was rejected in review |
verify.session.needs_review | A verification needs a person to decide |
verify.session.expired | A link wasn't finished in time |
verify.session.canceled | A verification was canceled |
verify.session.redacted | A verification's data was deleted |
Events carry the session without the data read from the ID. Read the session with the API for that.