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.

  1. 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.
  2. Copy the signing secret. It is shown once, at creation, and cannot be read back afterwards. If it is lost, rotate it.
  3. Pick the event types. Whole groups can be selected, see below.
  4. 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.
  5. 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"
    }
  }
}
FieldTypeDescription
idstringThe occurrence. Stable across retries, redeliveries, and every endpoint that receives it — this is what you dedupe on.
typestringEvent type, e.g. `order.completed`.
createdstringWhen it happened, ISO 8601 UTC.
api_versionstringThe generation of this contract. Informational — we only ever add fields, so you do not need to branch on it.
org.idstringThe organisation this event belongs to.
org.slugstring | nullTheir URL segment on stello.no.
data.objectobject | nullThe 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.*

TypeObjectSent when
membership.purchasedmembership_passWhen the pass is minted, immediately after payment is captured. Free memberships emit this too.
membership.refundedmembership_passWhen 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.*

TypeObjectSent when
order.completedorderWhen the order moves to `completed`, whichever way it was bought: in the app, at a card terminal, or through web checkout.
order.refundedorderWhen the order moves to `refunded` or `partially_refunded`. Read `refunded_amount` rather than assuming the whole order went back.

Events event.*

TypeObjectSent when
event.publishedeventWhen the event moves into `published` from any other status, including when a scheduled event publishes itself at its `publish_at` time.
event.updatedeventWhenever 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.canceledeventWhen the event moves into `canceled`. `cancel_reason` carries the organiser’s note if they left one.

People person.*

TypeObjectSent when
person.email_changedpersonWhen 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.

FieldTypeDescription
idstringStello identifier for the pass. Immutable.
object"membership_pass"Always `membership_pass`.
org_idstringThe organisation the membership belongs to.
statusstring`active` or `refunded`. Expiry is not a status — compare `valid_until`.
member.idstring | nullStable 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.emailstring | nullLower-cased email the member bought under. Can change over time: match on `id`, keep this for contact.
member.first_namestring | nullGiven name.
member.last_namestring | nullFamily name.
membership_idstringThe membership scheme, e.g. "Medlemskap 2026".
membership_type.idstringThe tier that was bought.
membership_type.namestring | nullTier name as it read at purchase.
order_idstring | nullThe 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_reasonstring | nullWhy 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_modestring`auto` (valid from purchase) or `manual` (valid from the scan that activates it).
single_usebooleanA single-use pass, consumed by the scan that activates it.
activated_atstring | nullNull on a manual pass nobody has activated yet.
valid_fromstring | nullStart of the validity window.
valid_untilstring | nullEnd 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_paidnumber | nullWhat the member paid, in øre.
currencystring | nullISO 4217, lower case.
purchased_atstringWhen the pass was minted.

The order object

Delivered by order.completed, order.refunded.

FieldTypeDescription
idstringStello identifier for the order. Immutable.
object"order"Always `order`.
org_idstring | nullThe organisation the sale belongs to.
receipt_numberstringHuman-facing reference, `STL-YYYY-NNNNN`. What a buyer will quote you.
statusstringOne of `pending`, `completed`, `refunded`, `partially_refunded`, `canceled`, `failed`, `expired`.
currencystringISO 4217, lower case. Always `nok` today.
subtotal_amountnumberTicket or membership price before discount and fees, in øre.
discount_amountnumberDiscount applied, in øre.
listed_amountnumberWhat 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_orgnumberThe organisation’s share before any refunds, in øre.
refunded_amountnumberReturned to the buyer so far, in øre. Zero on a fresh order.
coupon_codestring | nullDiscount code used, as typed.
event_idstring | nullSet on a ticket order, null on a membership order.
membership_idstring | nullSet on a membership order, null on a ticket order.
item_countnumber | nullNumber of tickets in the order.
buyer.idstring | nullStable 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.emailstring | nullLower-cased email the buyer bought under. Can change over time: match on `id`, keep this for contact.
buyer.first_namestring | nullGiven name.
buyer.last_namestring | nullFamily name.
completed_atstring | nullWhen payment was captured.
refunded_atstring | nullWhen it was fully refunded.
created_atstringWhen the order was opened.
updated_atstring | nullLast change, ISO 8601 UTC.

The event object

Delivered by event.published, event.updated, event.canceled.

FieldTypeDescription
idstringStello identifier for the event. Immutable.
object"event"Always `event`.
org_idstringThe organisation that owns the event.
titlestringEvent title as shown to students.
slugstringURL segment. Editable by the organiser, so never use it as a key.
descriptionstring | nullLong description, plain text.
statusstringOne of `draft`, `scheduled`, `published`, `unlisted`, `canceled`, `ended`. New values may be added.
starts_atstringISO 8601 UTC start time.
ends_atstringISO 8601 UTC end time.
publish_atstring | nullWhen a scheduled event becomes public. Null unless scheduled.
first_published_atstring | nullThe first time this event was ever published. Null while it is a draft.
location.namestring | nullVenue name or custom label.
location.addressstring | nullStreet address.
location.citystring | nullMunicipality.
location.latitudenumber | nullDecimal degrees.
location.longitudenumber | nullDecimal degrees.
image_urlstring | nullCover image, publicly readable.
categoriesstring[]The organiser’s categories, as Norwegian labels. Up to three, and the vocabulary grows.
min_agenumber | nullVenue-wide minimum age.
age_notestring | nullFree-text qualifier on the age limit, e.g. "20 for baren".
max_capacitynumber | nullHard cap shared across all ticket types. Null means uncapped.
cancel_reasonstring | nullThe organiser’s note, present only when the event was canceled.
urlstring | nullPublic page for the event on stello.no.
updated_atstring | nullLast edit, ISO 8601 UTC.

The person object

Delivered by person.email_changed.

FieldTypeDescription
idstring | nullStable 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_idstringYour organisation.
emailstring | nullTheir email now, lower case.
previous_emailstring | nullThe address they had before this change. For records you created before `id` existed.
first_namestring | nullGiven name.
last_namestring | nullFamily name.
changed_atstring | nullWhen 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:

FieldTypeDescription
Stello-Event-TypestringSame as `type` in the body, so you can route before parsing.
Stello-Event-IdstringSame as `id` in the body. This is what you deduplicate on.
Stello-Delivery-IdstringThis 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.