Specific terms

[Jeff Lindsay]

If somebody wants to make a wiki page for this, it might be a good idea. I'd like to try and come up with consensus on terms for the parts of a webhooks system.

First of all, I think webhooks represent the architectural pattern, and although we can get away with saying "this app has webhooks", it helps to have more specific working definitions. I think webhooks inherit the same ambiguity of "hooks" in programming: is the hook the callback (noun) or the code the calls back (verb) or the API to register the hook? There is a sort of paradox where, in general, people will refer to the conceptual idea of where you "hook-in" as being the hook, and some people refer to the callback as "the hook." Because of this, I think we should not use "hooks" or "webhooks" in the specific terminology and reserve it for the general pattern.

I stumbled across a wiki page a while back that was thinking along the same lines as I was (around the same time, a little after my first publication) that called them triggers, like in the DB world. Recently, somebody implemented webhooks and decided to call that feature in their terms "triggers" ... a while back I decided that was a great term that refers to the part of the system that actually invokes the callback (calls back). Therefore, you can say that apps that support/implement/have webhooks more specifically implement "webhook triggers". You can now refer to that bit of code that "invokes the webhook" as trigger code, or "the trigger."

Another source of trouble is the callback itself. Traditionally this is quite clearly a function ... although in most cases it's actually a function pointer. This most directly maps to the URL of the "hook script." Therefore, the "callback" in a webhooks system should very specifically be the URL. This also explicitly keeps clear the abstraction of implementation. The trigger doesn't care about the actual code (if any) behind the URL. It just posts to the URL.

Now those that like the Observer pattern are going to want to call the callback an observer, and those that like event-driven programming will want to call it an event listener. I'm not sure how much to use of these terminologies. Both are definitely more modern I think, but both are implemented using callbacks. I definitely want to avoid, say, "subscriber" as that implies more specific uses, such as "subscribing to content" ... this starts limiting the uses of this tech, but makes sense in actual PubSub systems like Hubbub.

What do you guys think? How do you break down the nouns and verbs in a webhooks system?

--
Jeff Lindsay
http://webhooks.org -- Make the web more programmable
http://shdh.org -- A party for hackers and thinkers
http://tigdb.com -- Discover indie games
http://progrium.com -- More interesting things

[Daniel Parker]

Made a new page, http://wiki.webhooks.org/Terminology. I just started it with all the terms I could think of really quickly, but we won't want all of them. I wanted to start with as many as I could think of that have been used, and then we can talk about which ones to officially not use and which ones should be officially defined.

- daniel parker -

"You have granted me life and steadfast love, and your care has preserved my spirit." Job 10:12
"The LORD is my chosen portion and my cup . . . indeed, I have a beautiful inheritance." Psalm 16:5-6
"Give what you can ... take nothing back!"

[S Sriram]

Hi,

 

First of all, I think webhooks represent the architectural pattern, and although we can get away with saying "this app has webhooks", it helps to have more specific working definitions. I think webhooks inherit the same ambiguity of "hooks" in programming: is the hook the callback (noun) or the code the calls back (verb) or the API to register the hook? There is a sort of paradox where, in general, people will refer to the conceptual idea of where you "hook-in" as being the hook, and some people refer to the callback as "the hook." Because of this, I think we should not use "hooks" or "webhooks" in the specific terminology and reserve it for the general pattern.

I think that although this line of thinking i.e. (webhook as the architectural pattern) makes theoretical sense, 

practically I think making webhook == the callback url

makes it easy to think/communicate i.e. you call/trigger the webhook/url

S. Sriram

[Jeff Lindsay]

Thanks! I added some more terms, including others I've heard around. I also added more info, connotations, some structure. Maybe too much structure? Feel free to add and edit with your own notes, etc.

[Jeff Lindsay]

I think that although this line of thinking i.e. (webhook as the architectural pattern) makes theoretical sense, 

practically I think making webhook == the callback url

makes it easy to think/communicate i.e. you call/trigger the webhook/url

Yes, I keep coming back to the idea that hook will not be avoidable in terminology. So you're probably right. Remember, webhooks was originally just shorthand for the idea of "hooks, on the web" ...