Integrated webhook support for transaction events

[s8sato]

I don’t ask for crypto. M◉⃤|<𓊖༒𓊖⛦ Takemiya 武宮誠 (Sora.org & SORAMITSU), [2025/06/28 19:34] Do we currently have the ability in Iroha through our APIs for webhooks? For many use cases, external systems need to get pushed information when certain types of transactions are performed.

S. Sato, [2025/06/30 10:10] There is a mechanism to push transaction-commit events, but there isn't a way to register arbitrary POST requests in Iroha and drive them by events. For that, we currently need to rely on an external service.

I don’t ask for crypto. M◉⃤|<𓊖༒𓊖⛦ Takemiya 武宮誠 (Sora.org & SORAMITSU), [2025/06/30 14:12] We should probably do a more integrated webhook design to minimize trust, as it is commonly needed. Let's document this so we can look at it in the future

[0x009922]

Webhook integration directly in Iroha seems problematic to me.

First, in terms of data, I'd define webhooks as a combination of event filters + some arbitrary URL to make some POST request to it with the event payload.

I see the following ways of implementation:

1. Users declare webhooks statically on Iroha startup (via config/CLI). This is not flexible and probably not viable for real-world scenarious (have to perform costly restart to register/unregister webhooks; have to be admin to access the infra).
2. Users register webhooks dynamically. Here, I see multiple choices as well:
   1. Add a new HTTP API (e.g. POST /events/webhook/DELETE /events/webhook) to register/unregister webhooks. This comes with a question of where to store the registered webhooks:
      1. Use volatile in-memory storage. Easy to implement, but all registered hooks will be lost on restart.
      2. Introduce some kind of persistent storage alongside the block storage. This adds some new headaches to infra (more set up). We would also like to make the entire webhooks feature optional, which makes internals more complex.
      3. Introduce an integration with some external storage (Iroha & Redis/SQLite/PostgreSQL) for these needs. This approach is not very flexible as it requires Iroha to support a specific storage.
   2. Extend the Transactions API. This means all hooks will be stored in the blockchain and shared among all peers. Pros: no need to invent a new storage; simply extend instructions set. Cons: either webhooks will be triggered by each and every peer in the network (which would be insane for the receiving part), or webhooks must be assigned somehow to particular peer IDs who will fire them.

IMO, from the above list, the most seemingly adequate option is 2.i.c. However, I don't think this wins over an external implementation. It is straightforward to implement an external microservice with its own DB/Redis that will serve as a webhook proxy. It is possible to do already now. This approach seems way more modular and composable to me.