Stello for developers
Webhooks
Stello sends a signed HTTPS POST to your server whenever something happens in an organisation you work with, so your own systems can stay in step without anyone retyping anything.
API version 2026-09-01
Setting up
An organisation admin creates endpoints under Utviklere (Developers) in the Stello dashboard. The dashboard is in Norwegian, so button names are given here as they appear, with a translation the first time. An organisation can have up to five, each with its own secret and its own list of event types.
- Add the HTTPS address your server listens on. It has to be reachable from the public internet; we refuse private addresses and never follow redirects.
- Copy the signing secret. It is shown once, at creation, and cannot be read back afterwards. If it is lost, rotate it.
- Pick the event types. Whole groups can be selected, see below.
- Optionally narrow it to specific memberships or specific events. Scoping is invisible to you as the receiver: a scoped endpoint simply gets fewer deliveries, and every payload is identical to an unscoped one’s. An organisation that leaves it open receives everything, including memberships and events they create later.
- Send the test event, confirm your server answers, then switch the endpoint on. New endpoints start switched off on purpose: until the secret is in place, everything we send would fail verification.
Picking a whole group (for example all event.*) also gets you event types we add to that group later. Those carry the same object your code already handles, so only the type string is new. An entirely new group never reaches an endpoint until somebody ticks it, because that would be an object your code has never seen.
The envelope
Every delivery is one JSON object with the same shape. The resource it is about sits at data.object.
{
"id": "we4d2k9p4x1n6v3b8c5q0w2e",
"type": "membership.purchased",
"created": "2026-08-31T14:22:07.000Z",
"api_version": "2026-09-01",
"org": {
"id": "j57d2k9p4x1n6v3b8c5q0w2e",
"slug": "demo-studentforening"
},
"data": {
"object": {
"id": "ms7d2k9p4x1n6v3b8c5q0w2e",
"object": "membership_pass",
"org_id": "j57d2k9p4x1n6v3b8c5q0w2e",
"status": "active",
"member": {
"id": "per_7Kq2Xw9mRb4Tn6Vc",
"email": "kari.nordmann@stud.ntnu.no",
"first_name": "Kari",
"last_name": "Nordmann"
},
"membership_id": "mb1d2k9p4x1n6v3b8c5q0w2e",
"membership_type": {
"id": "mt3d2k9p4x1n6v3b8c5q0w2e",
"name": "Ordinært medlemskap"
},
"order_id": "m42d2k9p4x1n6v3b8c5q0w2e",
"issued_reason": null,
"activation_mode": "auto",
"single_use": false,
"activated_at": "2026-08-31T14:22:07.000Z",
"valid_from": "2026-08-31T14:22:07.000Z",
"valid_until": "2027-08-31T14:22:07.000Z",
"amount_paid": 25000,
"currency": "nok",
"purchased_at": "2026-08-31T14:22:07.000Z"
}
}
}| Field | Type | Description |
|---|---|---|
| id | string | The occurrence. Stable across retries, redeliveries, and every endpoint that receives it — this is what you dedupe on. |
| type | string | Event type, e.g. `order.completed`. |
| created | string | When it happened, ISO 8601 UTC. |
| api_version | string | The generation of this contract. Informational — we only ever add fields, so you do not need to branch on it. |
| org.id | string | The organisation this event belongs to. |
| org.slug | string | null | Their URL segment on stello.no. |
| data.object | object | null | The resource this event is about. Which object depends on the type — see the table above. Null on `webhook.test`. |
We only ever add fields. Names and meanings of existing fields do not change, so you do not need to branch on api_version; it is there for support conversations and your own logs. New keys can appear in any object at any time, so parse leniently.
On personal data: a name and an email address are the only personal data Stello sends. No phone numbers, no dates of birth, no answers to checkout questions. There is no setting that changes this.
Event types
Memberships membership.*
| Type | Object | Sent when |
|---|---|---|
| membership.purchased | membership_pass | When the pass is minted, immediately after payment is captured. Free memberships emit this too. |
| membership.refunded | membership_pass | When the pass moves to `refunded`. This is the signal to revoke whatever access the membership granted in your own system — Stello's copy stops being valid at the same moment. |
Orders order.*
| Type | Object | Sent when |
|---|---|---|
| order.completed | order | When the order moves to `completed`, whichever way it was bought: in the app, at a card terminal, or through web checkout. |
| order.refunded | order | When the order moves to `refunded` or `partially_refunded`. Read `refunded_amount` rather than assuming the whole order went back. |
Events event.*
| Type | Object | Sent when |
|---|---|---|
| event.published | event | When the event moves into `published` from any other status, including when a scheduled event publishes itself at its `publish_at` time. |
| event.updated | event | Whenever any field of the `event` object below actually changes value. Internal bookkeeping that is not part of the object never emits this, so a mirror can apply every one of these blindly. |
| event.canceled | event | When the event moves into `canceled`. `cancel_reason` carries the organiser’s note if they left one. |
People person.*
| Type | Object | Sent when |
|---|---|---|
| person.email_changed | person | When a person changes the email on their Stello account, and only to organisations where they currently hold something: a membership that has not expired or been refunded, or a ticket to an event that has not ended. Match on `id`; `previous_email` is there for records you created before ids existed. |
An event object is an arrangement, not a webhook event. The webhook event is the envelope around it.
Objects
Every key listed here is always present. Values we do not hold are null rather than omitted, so you can rely on the shape. Amounts are integer øre.
The membership_pass object
Delivered by membership.purchased, membership.refunded.
| Field | Type | Description |
|---|---|---|
| id | string | Stello identifier for the pass. Immutable. |
| object | "membership_pass" | Always `membership_pass`. |
| org_id | string | The organisation the membership belongs to. |
| status | string | `active` or `refunded`. Expiry is not a status — compare `valid_until`. |
| member.id | string | null | Stable identifier for the member, `per_…`. Never changes, even when they change their email, so it is the field to match on. Unique to your organisation. |
| member.email | string | null | Lower-cased email the member bought under. Can change over time: match on `id`, keep this for contact. |
| member.first_name | string | null | Given name. |
| member.last_name | string | null | Family name. |
| membership_id | string | The membership scheme, e.g. "Medlemskap 2026". |
| membership_type.id | string | The tier that was bought. |
| membership_type.name | string | null | Tier name as it read at purchase. |
| order_id | string | null | The order that paid for this pass. Null when the organisation handed the membership out for free from their dashboard — there is no order, no receipt and no payment behind it. |
| issued_reason | string | null | Why the organisation gave the membership away, in their own words (e.g. "æresmedlem"). Set only on a pass with no `order_id`, and what stands in for the receipt on one. |
| activation_mode | string | `auto` (valid from purchase) or `manual` (valid from the scan that activates it). |
| single_use | boolean | A single-use pass, consumed by the scan that activates it. |
| activated_at | string | null | Null on a manual pass nobody has activated yet. |
| valid_from | string | null | Start of the validity window. |
| valid_until | string | null | End of the validity window. Null when the pass never expires, or is not activated yet. Expire locally from this rather than waiting for us to tell you. |
| amount_paid | number | null | What the member paid, in øre. |
| currency | string | null | ISO 4217, lower case. |
| purchased_at | string | When the pass was minted. |
The order object
Delivered by order.completed, order.refunded.
| Field | Type | Description |
|---|---|---|
| id | string | Stello identifier for the order. Immutable. |
| object | "order" | Always `order`. |
| org_id | string | null | The organisation the sale belongs to. |
| receipt_number | string | Human-facing reference, `STL-YYYY-NNNNN`. What a buyer will quote you. |
| status | string | One of `pending`, `completed`, `refunded`, `partially_refunded`, `canceled`, `failed`, `expired`. |
| currency | string | ISO 4217, lower case. Always `nok` today. |
| subtotal_amount | number | Ticket or membership price before discount and fees, in øre. |
| discount_amount | number | Discount applied, in øre. |
| listed_amount | number | What the organisation sold it for, in øre: subtotal minus discount. This is the sale price, not the buyer’s card charge — service fees and payment-method premiums are not included, and deliberately never are. |
| amount_to_org | number | The organisation’s share before any refunds, in øre. |
| refunded_amount | number | Returned to the buyer so far, in øre. Zero on a fresh order. |
| coupon_code | string | null | Discount code used, as typed. |
| event_id | string | null | Set on a ticket order, null on a membership order. |
| membership_id | string | null | Set on a membership order, null on a ticket order. |
| item_count | number | null | Number of tickets in the order. |
| buyer.id | string | null | Stable identifier for the buyer, `per_…`. Never changes, even when they change their email, so it is the field to match on. Unique to your organisation. |
| buyer.email | string | null | Lower-cased email the buyer bought under. Can change over time: match on `id`, keep this for contact. |
| buyer.first_name | string | null | Given name. |
| buyer.last_name | string | null | Family name. |
| completed_at | string | null | When payment was captured. |
| refunded_at | string | null | When it was fully refunded. |
| created_at | string | When the order was opened. |
| updated_at | string | null | Last change, ISO 8601 UTC. |
The event object
Delivered by event.published, event.updated, event.canceled.
| Field | Type | Description |
|---|---|---|
| id | string | Stello identifier for the event. Immutable. |
| object | "event" | Always `event`. |
| org_id | string | The organisation that owns the event. |
| title | string | Event title as shown to students. |
| slug | string | URL segment. Editable by the organiser, so never use it as a key. |
| description | string | null | Long description, plain text. |
| status | string | One of `draft`, `scheduled`, `published`, `unlisted`, `canceled`, `ended`. New values may be added. |
| starts_at | string | ISO 8601 UTC start time. |
| ends_at | string | ISO 8601 UTC end time. |
| publish_at | string | null | When a scheduled event becomes public. Null unless scheduled. |
| first_published_at | string | null | The first time this event was ever published. Null while it is a draft. |
| location.name | string | null | Venue name or custom label. |
| location.address | string | null | Street address. |
| location.city | string | null | Municipality. |
| location.latitude | number | null | Decimal degrees. |
| location.longitude | number | null | Decimal degrees. |
| image_url | string | null | Cover image, publicly readable. |
| categories | string[] | The organiser’s categories, as Norwegian labels. Up to three, and the vocabulary grows. |
| min_age | number | null | Venue-wide minimum age. |
| age_note | string | null | Free-text qualifier on the age limit, e.g. "20 for baren". |
| max_capacity | number | null | Hard cap shared across all ticket types. Null means uncapped. |
| cancel_reason | string | null | The organiser’s note, present only when the event was canceled. |
| url | string | null | Public page for the event on stello.no. |
| updated_at | string | null | Last edit, ISO 8601 UTC. |
The person object
Delivered by person.email_changed.
| Field | Type | Description |
|---|---|---|
| id | string | null | Stable identifier for the person, `per_…`. The same value as `buyer.id` and `member.id` on their orders and passes, and the key to update your record by. |
| object | "person" | Always `person`. |
| org_id | string | Your organisation. |
| string | null | Their email now, lower case. | |
| previous_email | string | null | The address they had before this change. For records you created before `id` existed. |
| first_name | string | null | Given name. |
| last_name | string | null | Family name. |
| changed_at | string | null | When the change happened. |
Verifying the signature
Every request carries a Stello-Signature header:
Stello-Signature: t=1756640000,v1=<hex>[,v1=<hex>]Each v1 is an HMAC-SHA256, in lower-case hex, over the string `${t}.${rawBody}`, keyed with your endpoint secret. There can be more than one, and any match is a pass. For 24 hours after a rotation we sign with both the new and the previous secret, which is what lets you switch over without a single failed delivery.
import { createHmac, timingSafeEqual } from 'node:crypto';
const TOLERANCE_SECONDS = 300;
export function verify(rawBody: string, header: string, secret: string): boolean {
// "t=1756640000,v1=<hex>,v1=<hex>"
const parts = header.split(',').map((p) => p.trim());
const timestamp = parts.find((p) => p.startsWith('t='))?.slice(2);
const signatures = parts.filter((p) => p.startsWith('v1=')).map((p) => p.slice(3));
if (!timestamp || signatures.length === 0) return false;
// Reject anything too old. The timestamp is inside the signed material, so a
// captured delivery cannot be replayed later with a fresh t.
const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) return false;
const expected = createHmac('sha256', secret)
.update(`${timestamp}.${rawBody}`)
.digest('hex');
// ANY signature matching is a pass. During the 24 hours after a secret
// rotation we sign with both the new and the old key, which is what lets you
// paste the new secret in whenever you like with nothing failing either side.
// Comparing only signatures[0] works today and breaks silently a year from
// now, on the afternoon somebody rotates.
return signatures.some((candidate) => {
const a = Buffer.from(candidate, 'hex');
const b = Buffer.from(expected, 'hex');
return a.length === b.length && timingSafeEqual(a, b);
});
}Other headers on every request:
| Field | Type | Description |
|---|---|---|
| Stello-Event-Type | string | Same as `type` in the body, so you can route before parsing. |
| Stello-Event-Id | string | Same as `id` in the body. This is what you deduplicate on. |
| Stello-Delivery-Id | string | This attempt. Different on every retry and every manual resend. Quote it to support. |
Delivery and retries
At least once, and unordered. Retries mean the same event can arrive twice, and a retried delivery can land after a newer one. Deduplicate on id, and use created to discard anything older than what you already hold for that object.
app.post('/stello/webhook', express.raw({ type: 'application/json' }), (req, res) => {
// Verify against the RAW bytes. Re-serialising the parsed object changes key
// order and whitespace, and the signature will not match.
const raw = req.body.toString('utf8');
if (!verify(raw, req.header('Stello-Signature') ?? '', process.env.STELLO_SECRET!)) {
return res.sendStatus(401);
}
const event = JSON.parse(raw);
// Answer 200 to types you do not recognise. We add event types over time, and
// an endpoint subscribed to a family receives new verbs in that family
// automatically. A 400 here is terminal on our side and counts towards the
// failure streak that switches your endpoint off.
switch (event.type) {
case 'membership.purchased':
// Idempotent: the same event.id can arrive twice, and order is not
// guaranteed. Store the id and ignore repeats.
upsertMember(event.id, event.data.object);
break;
default:
break;
}
// Answer fast, work afterwards. We give up on a request after 10 seconds and
// retry it later, which for a slow database means duplicate work rather than
// no work.
res.sendStatus(200);
});- Answer within 10 seconds. Past that we abort and retry later. Return 200 first and do slow work afterwards.
- 2xx is success. The body is ignored.
- 4xx is final. We do not retry it, because sending the same request again would get the same answer. It counts against your endpoint.
- 5xx, a timeout or a connection failure is retried with exponential backoff over roughly a day.
- Redirects are refused. A 3xx is a failed delivery, not a hop.
- Endpoints that keep failing get switched off. After 24 failed deliveries in a row, or 72 hours of unbroken failure, we disable the endpoint and email the organisation. Nothing is lost: switch it back on and press Send det som mangler (“send what is missing”) to receive everything from the outage.
- The log reaches back 30 days. Every attempt, with the status and the first 500 bytes of your response, is visible in the dashboard, and any of them can be resent by hand. Past 30 days it is deleted.
Testing
The Send testhendelse (“send test event”) button posts a webhook.test event to one endpoint. It proves reachability, TLS and signature verification, which are the things that are actually wrong during setup. It carries no object and is tied to nothing real:
{
"id": "we0d2k9p4x1n6v3b8c5q0w2e",
"type": "webhook.test",
"created": "2026-08-31T14:22:07.000Z",
"api_version": "2026-09-01",
"org": {
"id": "j57d2k9p4x1n6v3b8c5q0w2e",
"slug": "demo-studentforening"
},
"data": {
"object": null
}
}It is not in the catalogue and cannot be subscribed to. If your handler returns 400 for unknown types you will see it reported as “reached, type not recognised”. Returning 200 for types you do not know fixes that, and is what you want anyway.
To exercise a real handler, create an unlisted event with a free ticket and register yourself. That produces a genuine order.completed with real data you control, which is worth more than a synthetic sample.