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:
- The data is asked for in the way it is always asked for. The call to the papiNet API carries the partner's API key, is checked against the papiNet document, and returns only what your system allows that caller to see. A notification does not open a second, weaker way to the same data.
- The notification is small and safe to pass on. A CloudEvent's attributes travel in the clear and can be logged by anyone on the way, and the specification says to keep sensitive information out of them. A thin event has none to keep out.
- No size problem. CloudEvents guarantee only 64 KiB end to end. A delivery note or an order can be larger, so the document stays behind the API and the event points to it.
- Nothing replaces the protocols. A CloudEvent has no receipt, no signature and no encryption. AS2, ebMS and SFRM still carry the documents that need them. Notifications sit beside them.
From a change to the data, step by step
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) ◀═════════════════════════════════┘- Something changes in the supplier's system: a supplier order is confirmed, a delivery note is updated, stock moves.
- 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.
- 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.
- The partner's receiver checks it and puts it on the partner's queue, and answers only when the queue has it.
- 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.
- 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.
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:00ZThe partner's system then makes the call that the event pointed to, here for the supplier orders:
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.
- The partner has to agree first. Before the first delivery, Archr.Hermod asks the partner's receiver with an
OPTIONSrequest, as the CloudEvents web-hook specification describes, and sends nothing unless the partner answers that it accepts this sender. The key is not sent with that request. - The key is kept safe. It goes to Archr.Hermod's secret store, is never shown again and never logged.
The address must be
https(plainhttponly to the machine itself), carries no user name or password, and redirects are not followed. - Failures are told apart. A network error, a timeout, a
429or a5xxis tried again with growing waits, up to the number of attempts you set, and a rate the partner asks for is kept. Any other answer (a wrong key, a type the partner does not accept) is final. - Nothing is lost. An event the partner has not accepted is put on a dead-letter topic with the reason, the outcome and the number of attempts added, so an operator can see why and decide.
- In order. A partner's events go out one at a time in the order they arrived, and a partner that is down holds up only its own topic.
- Archr.Hermod's own acknowledgements can be sent on in the same way, as a thin event (
software.archr.hermod.message.acknowledged.v1, or…rejected.v1), with the message id as its subject.
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.
- A key for each partner. A receiver key is shown once, when it is made, and only a fingerprint of it is stored. It has an expiry date (a year unless you choose otherwise) and can be revoked, which stops it on the very next request. A receiver with no key accepts nothing.
- Only the senders and the events you agree. The receiver names the senders it accepts and the types of event it will take, and refuses a larger body than you set, or more requests a minute than the gateway allows.
- It answers honestly.
202only when the event is on your queue;401for a missing or wrong key;403for a sender or type that is not agreed;413too large;429too many;503when the queue did not take it, so the partner tries again. - Your system gets what was sent, untouched. The event goes onto the topic you chose, with the attributes as headers (
ce_on Kafka,ce-on NATS, as the CloudEvents bindings define) and the data exactly as it arrived. Any CloudEvents library can read it, and a system that knows nothing of CloudEvents still reads the data. In C#, the SDK's notification adapter reads the topic for you, hands each event to your handler, asks the partner's API for what changed, and takes care of repeats, retries and dead letters: SDK guide 4.
Switched on when you want it, and easy to try
- Off until an administrator switches it on, in Programmability > Settings, with no restart. Switched off, receivers answer as if they did not exist, and senders stop and leave their events on the topic until it is switched on again.
- One page shows how it is set up: the queue and whether it is healthy, the address partners must use, the receivers and senders and what each is doing, and a list of what needs attention (a receiver with no key, a queue that is not healthy, a public address that is missing or not https).
- A test button on every receiver sends a clearly marked test notification to the receiver's own topic, by way of its public address (or the gateway's own), so that you can see the address, the proxy, the certificate and the queue work before a partner relies on them.
- The papiNet Client, the demonstration application that comes with Archr.Hermod, has an Events page that listens to a topic and lists what arrives as it arrives. It talks to the queue only, so it needs no address, key or certificate of its own, and for a thin event it says that the document is to be fetched with a call.
What to know
- papiNet has not defined the events yet. Its text names the pattern and stops there: no event types, no payloads, and the direction is still being discussed. Archr.Hermod therefore carries any CloudEvent and invents no papiNet type names. You and your partner agree the types, and the gateway can be set to accept only those. When papiNet defines its own, they can be used as they are.
- An event can arrive twice. Delivery is at least once, as it is for every web-hook. The same
sourceandidis the same event, and the receiving system should act on it once. The ids of Archr.Hermod's own acknowledgement events are built from the message, so that a repeat has the same id. - Notifications are not the document. They say that something is ready. The data, its checks and its access control are the papiNet API's, which is described here, and the documents that need receipts, signatures or encryption go by the protocols in this reference.
- A dead-lettered event is moved back by hand for now; there is no automatic replay.