Events and webhooks
Everything that happens to your account’s screenings, as one stream you can read when you like — or have pushed to your webhook.
An event
{
"id": "0d6e…",
"seq": 1042,
"type": "screening.completed",
"createdAt": "2026-10-03T18:42:10.512Z",
"data": {
"screening": {
"id": "6f0c…",
"externalId": "lead-1042",
"portalUrl": "https://app.oncarousel.com/report/6f0c…"
}
},
"livemode": true
}seq only increases: it’s your place in the stream. Its numbering is shared, so expect gaps. Per screening, apply an event only if its seq is higher than the last one you applied; a screening’s screening.started is never numbered after its end. Events carry ids, your externalId and the link — never applicant data. They cover screenings sent from Carousel’s own screens too, where externalId is null. Your account’s stream starts when it creates its first key or webhook, and a new event appears within about a minute. livemode is false for a test key’s events and the webhook test.
Whose events they are
- Your account’s stream has the events of every screening filed in your account, whoever sent it, and your account’s building, unit and balance events.
- Copies of your sends. When one of your account’s keys sends a screening into a workspace another account shared with you, that screening’s events, and its application’s, are copied into your stream too — naming only your own
externalIds — for as long as you can still open it. When the share ends, the copies stop. A building your key adds there is theirs, and so is itsbuilding.created. GET /eventsreads your account’s stream through the key’s reach. It keeps the events of the screenings the key reaches, so a key that reaches this account’s workspaces only never reads the copies, and a key limited to some workspaces reads only their screenings’, buildings’ and units’ events. Balance events come to every key.- The webhook is the account’s. It gets the whole stream, copies included, whichever key sent the screening.
- Not yet: a screening that someone else sends in a workspace shared with you shows in
GET /screenings, but sends you no events.
Event types
GET /events/types returns each type with a one-line description.
Screenings
screening.sent— The screening was created and its applicant link issued.screening.invitation_delivered— Carousel’s mail service accepted the invitation email. It isn’t proof it arrived: a bounce after this isn’t reported.screening.invitation_failed— Carousel’s mail service didn’t accept the invitation email when it was sent — hand the applicant the link yourself. Carousel tries again for 24 hours, soscreening.invitation_deliveredcan still follow.screening.reminded— A reminder was sent to the applicant.screening.started— The applicant opened the application and started. A quick screening can go straight toscreening.completedwithout it.screening.step_completed— One check reached its end: done or stopped.GET /screenings/{id}says which.screening.completed— Every check is done — the report is ready.screening.viewed— The report was opened: by your team in Carousel (data.viaiscarousel), or in your platform through a view link (embed, withdata.viewer). Each load counts: a reload, the print view and every PDF download send one too.screening.cancelled— The screening was cancelled; nothing more is charged.screening.expired— The applicant never started within 30 days; the invitation expired.
data.screening is the screening’s id, externalId and portalUrl; step_completed adds data.check, the check’s id.
Applications
application.stage_changed— The application moved to another stage.application.note_added— Your team added a note (its text is not sent).application.moved— The application was filed under another workspace or building.
data.application is the application’s id and portalUrl; data.screenings lists its screenings with their id and externalId; stage_changed adds data.stage with its id and name.
Buildings and balance
building.created— A building was added.unit.created— A unit was added to a building.balance.low— Your token balance is below what one Verified+ screening costs. It comes again every 72 hours while it stays low, and after a top-up that runs low again.balance.exhausted— Your token balance ran out; token-paid sends are refused until a top-up.
data.building has its id, address and workspace; data.unit its id, label and building; balance events give the region.
Read them
curl "https://app.oncarousel.com/api/v1/events?after=0&limit=50" \
-H "Authorization: Bearer $CAROUSEL_API_KEY"Oldest first: { "data": [ … ], "cursor": 1042, "hasMore": false }. Save cursor and pass it as after next time; while hasMore is true, ask again straight away. types narrows it, comma-separated: types=screening.completed,screening.viewed. limit is 50 by default, and at most 200.
Events are kept. A webhook delivery you missed can always be read again here.
A webhook
In Carousel: account menu → Developers → Webhook. Enter one HTTPS address — an account has one — keep Every event or pick some, and save. Your signing secret (whsec_…) is shown once — copy it.
POST <your URL>
Content-Type: application/json
User-Agent: Carousel-Webhooks/1
Carousel-Event: screening.completed
Carousel-Delivery: <delivery id>
Carousel-Signature: t=1791060000,v1=<hex>
{ the event, as above }- Answer with any 2xx within 10 seconds. Otherwise we try again after at least 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours, then stop. The event stays in
GET /events. - Delivery is at least once, and not in order. Ignore a
Carousel-Deliveryyou’ve already handled, and order byseq. - Up to 300 deliveries a minute per address, a few at a time; after a failed delivery the rest wait a minute. On a busy account, read
GET /eventsas your main feed and treat each delivery as the prompt to read it. - Events are sent if they were recorded after you saved the address.
- Saving the address again creates a new signing secret, shown once, and stops pending deliveries to the old setup.
- The address must be public HTTPS, up to 500 characters: no IP addresses, no internal hosts. We don’t follow redirects.
- The Webhook tab lists the last ten deliveries and what your server answered.
Test your receiver without waiting for a real screening: POST /webhook/test, with any key, sends one signed sample event to your webhook now and answers with what your server said — its status code, or the error. The sample says "livemode": false and names no real screening. Send { "type": "…" } to choose its type (screening.completed if you leave it out); nothing else is taken. Up to 10 a minute per account; with no webhook set, it’s 404 not_found. A test key’s own events aren’t pushed to the webhook; read them with GET /events and that key.
Check the signature
The Carousel-Signature header is t=<unix seconds>,v1=<hex>. v1 is the hex HMAC-SHA256 of <t>.<raw body> — t, a dot, and the raw body — keyed with your signing secret. Recompute it before trusting a delivery. t and the signature are new on each attempt, and you may refuse an old t.
import crypto from 'node:crypto';
// rawBody: the request body exactly as received, before any JSON parsing
function isFromCarousel(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = crypto.createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`).digest('hex');
return expected.length === parts.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}import hashlib, hmac
def is_from_carousel(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
signed = parts["t"].encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])

