[Web Hooks] Spec Discussions

[Daniel Parker]

Jeff, guys, I just had a thought while reading this last message.

Replaying the thought (it was probably mine), "there are specific needs that can be addressed by slightly different protocols" -- after writing up the first part of the wiki.webhooks.org, including Jeff's original outline of the three major usage patterns (Push, Pipes, Plugins), I'm wondering if these are in fact the three major targets we should work on specs for.

In a sense, I'm thinking that the PubSubHubbub specs are primarily along the lines of Push, or in other words simple subscription to data. There will be certain preferences in this usage pattern (and group of use cases) that may be different from the other usage patterns. The spec I want to write is primarily for the Pipes pattern, and realizing this fact is going to be helpful in future discussions about specs. I would think the Plugins pattern would also have its own further preferences and needs, and it could have a spec of its own.

So in summary, I just wanted to share my half-revelation, that perhaps we should look at dividing our needs and use cases distinctly into these three camps, the three usage patterns, and think about specs with these divisions in mind as well.

If it were up to me, I would probably start three separate spec discussion groups and lay out a roadmap for each group laying out a schedule for the topics of discussions that need covered (4+ weeks "Needs & Priorities", 4+ weeks "All Possible Solutions", 4+ weeks "Debate It Out", 4+ weeks "Settle Debates and Finalize Documents"). Any thoughts on doing this? I'd be happy to create the groups and kick it off if there will be enough participants.

- 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!"

On Sat, Oct 10, 2009 at 3:14 PM, Jeff Lindsay <prog...@gmail.com> wrote:

I like that. I've always been payload neutral.

Regarding these different specs... I think ones with implementations are more likely to succeed. Hence my support of PubSubHubbub. However, I think it was Nathan that pointed out that there are specific needs that can be addressed by slightly different protocols. I think the needs for a specific convention need to be super clear if you're going to support something different.

Also, I know it's hard to get into something so different (since a lot of PubSubHubbub is not terribly relevant to general webhooks -- feeds and such), but I think the best way to attach it's lack of RESTfulness is from within. Meaning, contributing to it or an implementation (code AND spec over just spec, always!) and making incremental changes. Also, just being more actively in the discussion with Brett and Brad in particular is useful.

Anyway, I like the RESTful approach you're working on, but I think it's more likely bits and pieces of it will be used. I would love it if ideas from it were brought into PubSubHubbub for example.

On Sat, Oct 10, 2009 at 11:57 AM, Nathan <winder...@gmail.com> wrote:

Perhaps the best policy is to make no assertions about the payload. To
recommend that the resource not be placed in the payload, but not
prohibit it. If WebHooks explicitly states that all data necessary is
stored in the header and that the payload is free to contain anything.
WebHooks extensions such as WebFlow or SubPubHubs are then free to
dictate payload contents.

On Oct 10, 12:24 pm, Nathan <winder.nat...@gmail.com> wrote:
> > This topic is discussed at length in the form of light vs. fat pings

> > athttp://code.google.com/p/pubsubhubbub/wiki/ComparingProtocols It

> > brings up some important points that are not considered here.
>
> There were some interesting points there I have to admit. But in this
> case "Discussed" is a strong word. I see very little discussion, this
> document is PubSubHubBub justifying their use of fat pings. I am
> always skeptical of statistics that show that "my" method beats "your"
> method at every point. If fat pinging is as superior as is suggested
> in this document there would be no need to justify it. And I think the
> numbers for syndication are very different from those of WebHooks. A
> WebHook is  "generally" intended as a tool for moving resources from
> one provider to another, possibly transforming them on the way, not as
> a tool for broadcasting resources to millions of subscribers.
> PubSubHubBub probably cares very little about who receives a message
> or whether they receive it successfully and whether the resource state
> is represented accurately. They are just shooting messages out, if you
> get it good, if you don't that is just fine as well. I am looking to
> use WebHooks as an extension to a RESTful "API", data integrity and
> deliverability is critical for many of my use cases. And there are
> many cases where I never even need to see the resource, I may just be
> logging events or perhaps I am simply approving or denying a state
> change and can make that decision without accessing the resource.
>
> I am willing to bet that many of these points are completely valid and
> that in many ways fat pinging is superior when acting as a content
> distribution hub. The major concern that I have is state integrity as
> outlined in this and the previous post. Perhaps this topic requires
> some compromise. Perhaps we should allow concessions for resource
> inclusion. Perhaps two separate messaging modes one for fat pining
> messages who's integrity and delivery is non critical and one for
> messages that require those insurances. On a side note having the
> payload open for other content has a lot of advantages, particularly
> when you start viewing it in the context of WebFlow, where I may wan't
> to include a standardized event payload that contains links for
> actions like denying and approving the PUT command for a resource.

--

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

[Ethan Jewett]

Just to get this into the proper thread (didn't realize that the wiki
had just been updated in my previous email):

I think "Pipe" is a special case of "Push".

Actually, I think that a different way to describe the different
use-cases of webhooks might be synchronous and asynchronous push.

Push and Pipes are asynchronous. Plugin is synchronous (in that it
expects a response).

Ethan

[Daniel Parker]

Yup. Just different ways to explain it.

Like you said, yes they're all push. To distinguish the first two, you have to look at what is intended to be done with the data. In some cases, they could be synonymous, and in some cases, the purpose of providing the hook could cover both types of intentions. The third is much more distinct, because it assumes (and in many cases would require) a meaningful response. In some cases the response could be a by-product of the hook, and in other cases it could be the whole intent of the hook (Facebook / Google Wave robots).

Synchronous / Asynchronous is also another good indicator of the purpose of the hook.

For now, I think those words work. And they have the slight right of all starting with "P". We can thank Jeff Lindsay for that bit of ingeniousity. Do you think the definitions I wrote up on wiki.webhooks.org make sense? Are they easy enough to understand?

- 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!"

[Jeff Lindsay]

Push, pipes and plugins might not be specific enough for actual use cases, because I later split it into:

-Notifications
-Data syncing
-Chaining
-Modification
-Plugins

I do think Push/Pipes are roughly the same. It's more in the context. Which is even more the case here. The difference between the first three is how you use this tech in the greater system (data syncing is using notifications to push state changes to other apps, chaining is using notifications to trigger events across apps in serial). And the difference between "modification" and "plugins" is really in how formalize and how big of a deal it is. You might have a few "filter" based hooks, but you wouldn't call it a plugin system. Alternatively, something like Facebook App Platform is more of a "Platform" than plugin system just in how it's framed.

But when you get down to it, it's really just fire and forget (maybe with retry) vs fire and expect return. You can do the later async as well btw ... you just expect a return callback as opposed to waiting on the initial outgoing request.

-jeff

[Daniel Parker]

Yup, all true. Sooooo many possibilities, and how do we get a grasp on it to break it down into parts and understand the differences? And maybe we should be splitting it up in a totally different manner...

I'll keep thinking about those distinctions, and perhaps come up with more. I liked the simplicity of (and pictures depicting) "the three" in your old presentation on the topic. I think the right divisions will come with some logical illustrations like you had there. :)

- 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!"

[Nathan]

I feel like defining additional specs for use cases seems like
overkill and will just muddy the waters. Instead of just understanding
one concept/spec a user would have to evaluate several others to see
what "fits" their use case. And honestly I am still not convinced
there is a problem. How about instead of putting new specs on the
calendar we determine if there is even a real issue. For example,
please provide some uses cases that do not work with RESTful WebHooks.
I bet you will have a hard time doing so (a lot of that spec is based
on your feedback), RESTful WebHooks leaves most implementation details
for the provider to sort out, so it they want to support synchronous
messaging they include that option in the subscription resource
(payload) that gets posted when creating a subscription or when the
notifier creates the notification. I think a better approach is to
define implementation patterns and best practices that work over a
simple protocol like RESTful WebHooks. For example the WebFlow concept
that I have been throwing around may end up being a set of
implementation patterns but will still use RESTful WebHooks and should
require no change to the base messaging protocol. As I mentioned
before what we are really talking about are data flow patterns, I
think we need to identify use cases for the data flow patterns and
possible payload standards to go with them. But additional WebHook
specs seem like overkill (not the RESTful WebHooks is the only
solution, there may need to be another spec for non-RESTful WebHooks
as RESTful WebHooks requires RESTful implementations all around). Here
are the data patterns I mentioned before:

~ = lazy/async source data
s = sync source data
t = sync target data
x = no data

s&f = send-and-forget
s&b = send-and-block

>notify (x) s&f

>notify <reply (t) s&b

>notify >pull (~) s&f

>push (s) s&f

>push <reply (st) s&b

>push <pull (s~) s&f

>push <reply >pull (st~) s&b

As I mentioned in my email you could also have an acknowledgment
process that has these same 7 options coming the other direction.

> > On Sat, Oct 10, 2009 at 2:28 PM, Daniel Parker <dcpar...@gmail.com> wrote:
>
> >> Yup. Just different ways to explain it.
> >> Like you said, yes they're all push. To distinguish the first two, you
> >> have to look at what is intended to be done with the data. In some cases,
> >> they could be synonymous, and in some cases, the purpose of providing the
> >> hook could cover both types of intentions. The third is much more distinct,
> >> because it assumes (and in many cases would require) a meaningful response.
> >> In some cases the response could be a by-product of the hook, and in other
> >> cases it could be the whole intent of the hook (Facebook / Google Wave
> >> robots).
>
> >> Synchronous / Asynchronous is also another good indicator of the purpose
> >> of the hook.
>
> >> For now, I think those words work. And they have the slight right of all
> >> starting with "P". We can thank Jeff Lindsay for that bit of ingeniousity.
> >> Do you think the definitions I wrote up on wiki.webhooks.org make sense?
> >> Are they easy enough to understand?
>
> >> - 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!"
>

> >> On Sat, Oct 10, 2009 at 5:07 PM, Ethan Jewett <esjew...@gmail.com> wrote:
>
> >>> Just to get this into the proper thread (didn't realize that the wiki
> >>> had just been updated in my previous email):
>
> >>> I think "Pipe" is a special case of "Push".
>
> >>> Actually, I think that a different way to describe the different
> >>> use-cases of webhooks might be synchronous and asynchronous push.
>
> >>> Push and Pipes are asynchronous. Plugin is synchronous (in that it
> >>> expects a response).
>
> >>> Ethan
>

> >>> On Sat, Oct 10, 2009 at 3:13 PM, Daniel Parker <dcpar...@gmail.com>

> >>> > On Sat, Oct 10, 2009 at 3:14 PM, Jeff Lindsay <progr...@gmail.com>

> >>> >> On Sat, Oct 10, 2009 at 11:57 AM, Nathan <winder.nat...@gmail.com>

> ...
>
> read more »

[Jeff Lindsay]

Perhaps not high level use cases, but perhaps I'm thinking more of the details. I like the idea of conventions for specific things. This way you can build your own spec for your implementation a la carte. I know this goes against that whole idea of standardization, but it's part of the process of seeing what's used often and how. And a lot of the details of an implementation don't need to be standardized if they aren't a public interface for some common operation. Again, I'll point out all instances of webhooks now are useful despite there not being any sort of standard.

So not additional specs, but many "speclets" or conventions for specific things. Like defining failure callbacks or return callbacks, batching events, various methods of housekeeping/keep alive, seeing status of a hook, etc. Nobody on this list has talked about security implications. In some cases they aren't necessary, but in more public apps or depending on how you expose your API they are. PubSubHubbub is doing a lot of practical work in this area because its all intended to be public and at scale.

Like you said, a lot of these are implementation details and you want to focus on a simple protocol spec. However, you're focusing on covering 3 aspects with this simple protocol. Indeed, every implementation will have some sort of sub/pub interface, but how many *need* discovery. Is it ok if they don't use the discovery aspect?

What about people that can't entirely implement a restful interface, but want to use pieces of this? I'm only thinking out loud, so don't think I'm not approving the direction you're going.

I think what bothers me, is that it would be nice if we could boil down just the registration/subscription and call-back/publish interfaces to the simplest bare essentials. This is what we could call some sort of core spec that would already be mostly compatible with existing implementations and then from there implementers could decides whether they want to add discovery, or more restful resource meta-data, etc.

I wish we could make something just so super simple, but still enough to be called a spec, and focus on all our bigger ideas around that.

This would be a lot easier if I could just sit down and document all the webhook implementations. I love all this top-down design, but in order to be successful we need to have some bottom-up in there too. Is there anybody willing to help me get started documenting all instances of webhooks and how they work?

-jeff

[Nathan]

Hey Jeff,
I agree, and I don't say that very often :). I see opportunity to
define the "speclet" for the payload in an extensible manor. For
example, a subscription "object" should minimally have x, y, z
properties if it wants to support a given scenario. The implementor
could add additional properties for proprietary options. The spec
could be layered, you could implement the minimal, and then "plugin"
additional property sets (xml namespace) to open up those features/use
cases. Because RESTful WebHooks does not specify the payload it would
be possible to use different root "speclets" within RESTful WebHooks.
If there is a non-RESTful (Envelope) Spec it must also support this
level of flexibility. I have to run but will post more on this later.

> ...
>
> read more »

[Daniel Parker]

Same sentiment: I like the word "speclets" you've come up with. Shall we make it official? ;)

I've been thinking too that the best way to go is to define speclets, little bits of things that accomplish certain mini-purposes. A couple examples to add to the couple already mentioned:
1) If you want discovery, a good way to go about this is to add a couple of HTTP headers:

    X-WebHook-Location: [url] -- this lets the client know where to POST a webhook registration request.

    X-WebHook-Notify: Created, Updated, Deleted, Rated -- this lets the client know what events it can hook to. They could be anything, but try to use standard verbage whenever possible, such as the CRUD pattern.

    X-WebHook-Docs: [url] -- optional, the documentation for this site's WebHook implementation.

1b) If you want discovery but you can't modify your HTTP headers, then include these simply as <meta> tags in the HTML:

    <meta http-equiv="X-WebHook-Location" value="[url]" />, and so on.

2) If you want to make the hook receiver confirm its ability and willingness to receive a WebHook, a common method is to send an immediate first webhook message (POST) that asks for a confirmation. (this would have to be worked out...)

3) If you want to ... do this ...

Basically that pattern is what I'd like to see. We can work out these little speclets and use whatever combination of them we want to. If we ever get to a point where most of them are stable and people are following them, we could even add a discovery header that can list all of the speclets it uses (supported features).

- 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!"

[Jeff Lindsay]

Yep! However, I'd still love to collect data on existing implementations and extract some patterns from them too.

[robin]

Hi all,

It has been a while, but I have been buried here under a mountain of
admin. Anyway, I have had some time to think about the discussions
with a bit more detachment than usual. I hope no one minds me making
these points, as they may not seem directly relevant to the matter
under discussion, but I think that they are, in fact, very relevant.

It seems as though there is a conflict here (not an antagonistic one,
mind you) between those who see WebHooks as a kind of app or protocol
that needs to be defined so it can be implemented and those who see it
as a kind of approach. However, I see WebHooks as a series of simple
protocols and approaches to pass data between not very coordinated
nodes. This may seem trivial, but I really don't think it is. Rather
than thinking of WebHooks as a kind of protocol for notification, data
passing or linking, I see it more as a recognition of a different kind
of environment or space in which uncoordinated (or weakly coordinated)
distributed processing can happen.

In application programing we often think of datapassing as the trivial
glue that hooks functions together. In WebHooks, we are not really
concerned with the functions per se, except locally, but with the
passing points. As an example, let's say that we want to organize a
party. We can either sit down and design a set of games, food and
music that will be in certain places connected by clearly defined, and
standard, paths. We then design an invitation card, with clear
metadata attached, devise a list of guests, and then just post it out
to everyone. The posting is the trivial bit, the bit that gets very
little attention (but for the cost of stamps). Though I am sure that
parties do happen like this, they are not my kind of parties. Rather,
what happens is that a few of us, over a beer, decide that a party is
called for. We phone a few other people up and decide a place and
date. Some emails get sent, some SMS messages, to and from an ever
increasing group of people. The venue changes, as do the dates, and
now we have two parties rather than one. Some more tweets, SMSs, and
phone calls expand the group and some members of the expanding party
community decide on what CDs to bring. Others independently, but
passing the data around, decide on food and drink. Hay presto, we have
a stonking great party, perhaps two! This is what I see as WebHooks,
they are all those SMSs, tweets, texts, phone calls, etc., or rather
they are all the data that is being passed in those connections. None
of it standard, but for the specific protocols being used, and all the
data moving about, differentially, somewhat randomly, uncoordinated,
emerges as a party.

It is not that I wish to pour cold water on all the work on protocols
and definitions, but I do think that what Jeff is calling for here,
especially when he asked us to document the many different WebHook-
like implementations, is not to create a standard, but to emphasize
that this is an environment, a community of practice or a way of doing
things that has more in common with our party than with tea at the
Palace.

Best,

Robin

> ...
>
> read more »

[Chris Obdam]

Problem of course is for the end user to know which one of the implementation is used by the webhook provider.

Discovering in 3 ways seems to conflict with discovering in principle?

[Jeff Lindsay]

I'd avoid discovery as an example of your point because I think it's a special case. It's the simplest mechanism of all and is likely to easily be solved with a single mostly agreed upon spec/implementation.

[Nathan]

Robin, you have some good points and I think this ad hock approach is
desirable. The fact is that in your example there are "protocols" and
standards.

Discovery
you meet people, at a bar, on-line, at work, in they gym. When you
meet you exchange a greeting hello my name is "Joe" (exchange identity
info).

Subscription
Hi Joe, we party all the time, if you give me your phone number,
email, IM etc. I will let you know when we have one.

Notification
Send Joe and SMS, email, or IM.

As you can see all these concepts still apply. Even in our dynamic
lives there are protocols and standards. And wouldn't life be SOOOO
much easier if I could send a message to one location (a url)
associated with Joe instead of trying to catch him on SMS, Email, IM
etc? Send a message to Joe using one "protocol" and let Joe decide how
he want to receive it. I agree that things should be dynamic and
flexible but without standards Joe would approach me and say "Goobely
Gock", not realizing he is trying to introduce himself, I will
probably just ignore him.

> > On Wed, Oct 14, 2009 at 10:49 AM, Nathan <winder.nat...@gmail.com>  

> ...
>
> read more »

[Jeff Lindsay]

I think a point Robin was trying to make is that WebHooks shouldn't equate to a spec/protocol. I often compare it to AJAX as more of a design pattern. If any spec is associated with WebHooks, it should be the simplest, most universal thing possible. Anything else should probably be something else. For example, PubSubHubbub is a separate spec. It's own spec. For a particular purpose. Yet it's "based on webhooks."

[Nathan]

Daniel,
If you view the latest RESTful WebHooks recommendation the header
values have changed to a non-custom more standardized format: Eg. "X-
WebHooks-Location : URL" has changed to "Link : <URL>
rel=Subscription". I like the idea of allowing discovery to take place
in HTML, in addition to HTTP, using the html <Link rel=Subscription
href=URL/> in the head of the document (this could also be done in xml
possibly using xlink). I would like to suggest that unless we want to
debate the RESTful WebHooks recommendation we start using those terms,
as the header "X-WebHooks-Location" is no longer in the spec and may
just confuse people.

> ...
>
> read more »

[Jeff Lindsay]

I'll also point out in this already long thread that using Link in various document types (and http headers) is how PubSubHubbub is going with discovery. See, we're already converging! They currently use rel=Hub for practical reasons (their spec has a single endpoint for publish and subscribe that is the "Hub").

[Daniel Parker]

The fact that another [closely-related] spec is already using it is enough reason to switch. I was holding on to X-WebHooks-Location because it was more descriptive.

But, I'm still a little concerned about simply saying Link, URL, and rel=Subscription. There are more ways to subscribe other than WebHooks. So we'd be using header information that conveys a more generic idea than WebHooks. What if I want to provide an SMS number for SMS subscription, or a jabber id for jabber subscription? I know this might sound odd right now, but I just want to use the right words. If someone stumbles across the header, the verbiage should point them in the right direction. Right now I'd probably rather use rel=WebHook.

BTW: I do still like the idea of having the ability in the guidelines/speclet to allow several resources to use the same webhook registrar url (as PubSubHubbub does), rather than requiring a different subscription desk (url) for each resource.

- 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!"

[Nathan]

Every where I see WebHooks discussed whether in blogs or in person
(watched your videos) the first question seems to be, "ok, sounds
good, how do I implement it?" To which the reply is "WebHooks is a
concept, a development pattern..." to which most busy developers
reply, "Ok, thats nice. I'll wait till someone defines a spec, I am
too busy being innovative within my core competency to be waisting
time creating my own design that will be obsolete in a year when
WebHooks either defines a spec or gets replaced by REST-*Messaging".
What if OpenID or OAuth said "these concepts are abstract ideas,
implement them as you feel is best for you?" Everyone would have a
different definition for Federated and Delegated identity which
completely destroys the entire purpose of OpenID and OAuth. IMHO (who
am I kidding, my rants are rarely humble :) WebHooks falls into the
same category as OpenID and OAuth, it is an attempt to "connect" the
web, to organize the chaos in a way that provides greater value to the
citizens of the web. Trying to compare "WebHooks" to "Identity
Federation" or "Identity Delegation" without providing any guidelines
for implementation is a bit of a cop out.

> ...
>
> read more »

[Nathan]

Daniel,
I am going to suggest that any protocol specific data (SMS, Jabber
etc) be passed in the body of the request, no reason to include this
in the header. BTW REST-* Messaging is also using the Link: header.

> BTW: I do still like the idea of having *the ability* in the

> guidelines/speclet to allow several resources to use the same webhook
> registrar url (as PubSubHubbub does), rather than requiring a different
> subscription desk (url) for each resource.

You already can, simply set the discovery URL for each resources to
the same subscription URL. Then in the Body of your subscription post,
pass in the specific resource url. This is how semi-RESTful
PubSubHubbub would work.

On Oct 14, 11:45 am, Daniel Parker <dcpar...@gmail.com> wrote:
> The fact that another [closely-related] spec is already using it is enough
> reason to switch. I was holding on to X-WebHooks-Location because it was
> more descriptive.
> But, I'm still a little concerned about simply saying Link, URL, and
> rel=Subscription. There are more ways to subscribe other than WebHooks. So
> we'd be using header information that conveys a more generic idea than
> WebHooks. What if I want to provide an SMS number for SMS subscription, or a
> jabber id for jabber subscription? I know this might sound odd right now,
> but I just want to use the right words. If someone stumbles across the
> header, the verbiage should point them in the right direction. Right now I'd
> probably rather use rel=WebHook.
>

> BTW: I do still like the idea of having *the ability* in the

> guidelines/speclet to allow several resources to use the same webhook
> registrar url (as PubSubHubbub does), rather than requiring a different
> subscription desk (url) for each resource.
>
> - 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!"
>
>
>
> On Wed, Oct 14, 2009 at 1:18 PM, Jeff Lindsay <progr...@gmail.com> wrote:
> > I'll also point out in this already long thread that using Link in various
> > document types (and http headers) is how PubSubHubbub is going with
> > discovery. See, we're already converging! They currently use rel=Hub for
> > practical reasons (their spec has a single endpoint for publish and
> > subscribe that is the "Hub").
>

> ...
>
> read more »

[Jeff Lindsay]

Nathan,

I want there to be solid examples, and even how-tos that would play the role of a spec until there is something. I'd rather risk that now than have an overly complicated spec that solves problems that aren't real or for one particular use-case. So I completely agree, I just think we can satisfy with means other than a "spec" and it's my fault for not having anything good enough still after all this time. ;)

[Daniel Parker]

Daniel,
I am going to suggest that any protocol specific data (SMS, Jabber
etc) be passed in the body of the request, no reason to include this
in the header. BTW REST-* Messaging is also using the Link: header.

This was referring to the response, not the request. Which is where you put the Link: header. What I mean there is that for any resource, you may want to include information about types of Subscription (very general category) other than WebHooks, and if so, we shouldn't be claiming the entire category "Subscription" to mean "WebHooks".

[Daniel Parker]

Another, or perhaps further, perspective:

When WebHooks was first being pushed out there, it was put forth as a simple and smart design pattern. It was like, "duh, we should be doing things this way instead of making people poll our servers every few minutes and spending lots of our own time making our servers capable of answering all of those requests."

But as more people start to think about doing things "the WebHook way", new questions arise, just as Nathan said. Sure, the first principle of WebHooks is "do it this way (push rather than pull)". But Nathan and others are right, when you start to think about the implications of a callback, a lambda, on the web, suddenly the idea of a "programmable web" enters the horizon and it is actually within sight instead of a legend that nobody believes is possible.

When we start to think about the possibilities, WebHooks becomes in our mind not just a design pattern, but a path to the programmable web. So now our question is, "how do we get from here to there?" In our journey to the programmable web, is WebHooks the vehicle, or the road? I can see it being either, but I think some of us are confusing to others who don't have the same perspective, whether we are thinking of the vehicle, the road, or both. Do we need to separate and define terms?

In any case, let me clarify again: We don't need a spec for the vehicle, but we do need a spec (roadmap) for the road, the path to a "programmable web". This is why I wanted to start on a spec the moment I read about WebHooks, because I saw not just the vehicle and that it could go anywhere, but I saw a vehicle that could cross the previously impassable gap to the "programmable web". So we need specs. But what kind of specs? Now, I could write up a bunch of different kinds of specs today, but I don't want to produce the wrong results. I can see the programmable web in the distance, but I'm not sure of all the hills and valleys in between. This is why (agreeing with Jeff) we need to start with a few things that we know, and allow real implementations use them and push further, documenting the terrain. In a sense, we can build a toolkit out of things we've seen before, and send someone to head toward the "programmable web", hoping that our tools are adequate -- then they can report back and let us know which ones worked well and where/how they used them. We need several people to cut their paths there and back again before we can make an "official map" of the best path.

- 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!"

[Jeff Lindsay]

Sounds like we're mostly agreeing now. We have some actionable items: collect examples, document, extract patterns ... while continuing work on "speclet" style conventions (or groups of them as RESTful WebHooks seems to be). Let's shut down this thread and move on. Next topic! :)