API and webhooks

Another system can do three things with Noren today: get a message on every change (webhook), fetch the same messages (the feed), and post an item to a booking's bill. You manage keys and webhooks yourself under Integrations, Your own integrations; the example code is there too. See Your own integrations.

Open Your own integrations

Keys

• "Create key" asks for a name, the property and "What may this key do?": "Read events (the feed)" and/or "Charge a guest's bill". One key per system.
• The key is shown once. If it is lost, use "Revoke" and make a new one.
• Send it as Authorization: Bearer <key>. Limit: 120 requests per minute; above that, 429 with Retry-After.

Events

An event is thin: id (fixed, also on a retry), type, occurredAt, propertyId, object (booking, unit or day) and version, a sequence number per object without gaps. Only folio.charged and folio.voided also carry data with the line.

Types: booking.created, .confirmed, .modified, .cancelled, .room_assigned, .room_moved, .guest_updated, .online_checkin_completed, .checked_in, .checkin_reversed, .checked_out and .no_show; payment.received and .refunded; folio.charged and .voided; unit.housekeeping_changed; day.closed (midnight at the property). webhook.test only comes after "Test".

Webhooks

• An https address outside a local or internal network, with the types you chose. You see the secret (whsec_…) once.
• Each delivery is a POST with the headers x-noren-event, x-noren-event-id, x-noren-delivery, x-noren-timestamp and x-noren-signature. The signature is HMAC-SHA256 (hex) over timestamp.body, keyed with the secret. Refuse a timestamp more than five minutes off.
• Delivery is at least once, and the order is not fixed. Deduplicate on id; ignore a version that is not higher than the one you had.
• Answer within ten seconds with a 2xx. Otherwise up to ten attempts follow over just over two days. The "Delivery log" shows the last fifty; "Replay" sends the same id.

The feed

GET /api/v1/events?cursor=…&count=… with a key that may read events. Send the cursor from the answer with your next request. count is 100 by default, at most 500; a shorter page means you are up to date. Events are kept for thirty days.

The bill

GET /api/folio/{bookingId}/charge returns the bill; POST adds one item, with a required Idempotency-Key. The body is a catalogue item (extraId, quantity) or a free line (description, amountCents, vatRate, quantity, kind). No money moves.

Security

When your subscription ends, keys and webhooks are switched off straight away. How we secure things and where to report a weakness is on the "Trust" page of our site and in security.txt.

Not available yet

• A public API for bookings, availability, rates or guests. After an event you cannot yet fetch the state of a booking through the API.
• Looking up a booking through the API.