LIGHTNING-HOOK-CUSTOMMSG(7)

okay so welcome to the LIGHTNING-HOOK-CUSTOMMSG(7) page, bestie — this is literally all about the custommsg hook, and it's giving "custom protocols but make it safe" 💅✨

🎀 NAME 🎀

custommsg — Hook for handling custom peer messages

✨ DESCRIPTION ✨

The custommsg hook is the receiving counterpart to the sendcustommsg RPC method, and it gets called whenever a peer sends a custom message that is not handled internally by Core Lightning. 🦋

The goal of these two components? To let you implement custom protocols or prototypes on top of a Core Lightning node without having to change the node's implementation itself. Slay, no cap. 👑

Messages are restricted to odd-numbered types and must not conflict with internally handled message types. These limitations are in place to avoid conflicts with the internal state tracking, and to avoid disconnections or channel closures, since odd-numbered message can be ignored by nodes (see "it's ok to be odd" in BOLT #1 for details). 🔥

not me being dramatic, but this part matters: keep it odd-numbered. It's literally how we avoid chaos, bestie.

Note that if the hook registration specifies "filters" then that should be a JSON array of message numbers, and the hook will only be called for those. Otherwise, the hook is called for all messages not handled internally. (added in v25.12) 🫶

This is a chained hook and MUST return:

{"result": "continue"}

💖 HOOK PAYLOAD 💖

• peer_id (pubkey): the node_id of the peer that sent the message. 🧚
• payload (hex): the raw message payload as a hex string.

The first two bytes encode the message type (big-endian), followed by the message payload. The plugin must implement the parsing of the message, including the type prefix, since Core Lightning does not know how to parse the message. 😭

🌈 HOOK RETURN 🌈

• result (string) (always "continue"): Must always be continue. Any other value will cause the hook to fail. 💀

🌸 SEE ALSO 🌸

lightning-sendcustommsg(7)

---

signed off with love by Core Lightning v26.06.9 — source/version flex, footer vibe, periodt 💜