Technical Reference

Notifications: thin events with CloudEvents

Tell a partner that something has changed instead of letting them poll: a small CloudEvent says what and where, and the partner asks the papiNet API for the data.

When a supplier's data changes, the partners who need it usually find out by asking again and again. papiNet's 4.0.0 use-case documents describe exactly this: a logistics supplier cannot know when data has changed, so it has to poll the supplier's endpoints, which is wasteful. papiNet therefore recommends notifications, optional because they cost the logistics supplier an additional investment, and recommends the CloudEvents specification of the Cloud Native Computing Foundation, following the thin event pattern. Archr.Hermod sends and receives such notifications, and connects them to the papiNet API it already serves.

What a thin event is

A thin event says that something happened, not what the data now is. It carries just enough to find the change: what kind of thing happened (the type), which resource it is about (the subject), when, and who says so (the source), with an id that is the same if the notification is sent twice. The business data is not in it. The partner who receives it then asks the papiNet API for the data.

That suits papiNet's own API, and it is the reason to keep the data out of the notification:

From a change to the data, step by step

The path of a notification
your system ─▶ queue ─▶ your gateway ══ notification (HTTPS) ══▶ partner's gateway ─▶ queue ─▶ partner's system
     ▲                                                                                                     │
     └─── your gateway's papiNet API ◀══ the call for the data (API key) ◀═════════════════════════════════┘
  1. Something changes in the supplier's system: a supplier order is confirmed, a delivery note is updated, stock moves.
  2. The system puts a small event on a message-queue topic (NATS or Kafka), with no business data in it. It does not know the partner's address or key.
  3. Archr.Hermod delivers it to the partner over HTTPS, after asking the partner's receiver whether it agrees to receive from this sender. The key and the address are kept in Archr.Hermod. A partner that is busy is tried again, and an event that cannot be delivered is kept, not lost.
  4. The partner's receiver checks it and puts it on the partner's queue, and answers only when the queue has it.
  5. The partner's system reads the event and acts on it: the type and the subject say what to fetch. It asks the papiNet API for the new data, directly with its API key, or through its own outbound hub.
  6. The API answers as it always does, with the key, the validation and the caller's attributes applied, and the partner has the new data without having polled for it.

What a notification looks like

Over HTTP a CloudEvent in binary mode is an ordinary request: the attributes are ce- headers, and the data, if there is any, is the body. A thin event has no body. The type below is an example: papiNet has not yet defined any, so the partners agree theirs.

What the partner's receiver is sent
POST /cloudevents/supplier-a HTTP/1.1
Authorization: Bearer cek_<the key the receiver gave you>
WebHook-Request-Origin: gateway.supplier.example.com
ce-specversion: 1.0
ce-id: 7c1e0b5a-3f0c-4d2a-9d55-2b7f6a1e9c10
ce-source: urn:hermod:node:supplier
ce-type: com.example.supplier-order.updated
ce-subject: supplier-order/5821
ce-time: 2026-11-20T09:15:00Z

The partner's system then makes the call that the event pointed to, here for the supplier orders:

What the partner's system asks the papiNet API
GET /papinet/4.0.0/supplier-orders HTTP/1.1
X-Api-Key: <the key you gave the partner>

Structured mode (the whole event as JSON, application/cloudevents+json) can be sent too, and a receiver also accepts batches of events.

Sending notifications to a partner

A sender is set up for each partner in the Admin pages (Programmability > CloudEvents): the queue topic it listens to, the partner's HTTPS address, the key the partner gave you, and the name it announces itself by. Your system only puts an event on the topic.

Receiving notifications from a partner

A receiver is set up for each partner who sends you events, in the same place. Its address is /cloudevents/<name> on the partner-facing port of the gateway.

Switched on when you want it, and easy to try

What to know

← Back to the technical reference