Webhooks are in need of some standardisation for sure, so moving towards something like PuSH is a step in the right direction. However this technology has been around for a while, so whether this will become standard or not remains unclear.
PuSH solves a couple annoyances with webhooks that comes to my mind:
- Lack of debuggability: the inability to subscribe to events forces me to explicitly set up callback URL(s) on service providers' dashboards or in query strings in requests. IF I managed to set them up correctly, data will come crashing in any day in the future, throwing exceptions, or bouncing on unspecified routes. And all these POST catchers and local tunnels developers play with to get this right in the first place.
- Ad-hoc verification schemes: Every service comes up with their own way of ensuring the data originated from their servers. Signature hashes as 'X-*'-headers, a number of extra fields inside the JSON body, etc.
There are more, but these two has annoyed me for quite some time.
We've (Runscope) tried to make debugging better than what you can do with a simple post catcher like requestb.in. The nice thing about our forwarding setup is that if a webhook fails on your server you have a log of that and can retry it.
Nice article with a concise overview of PubSubHubbub and HTTP Subscription Specification. It would be really nice if you could complement it with pointers to some real example of interfaces using one or the other approach. This could help practitioners identify is the better fit for their use case.
The POST to /subscription line going from left to right is clear. What is the GET request below it, is that another HTTP GET requests or a the response to a POST. If it is a GET why is the arrow going from Server to Client.
Then the response to that GET has a 201 code but that is going from client to Server?
The POST to /subscription informs the API server that there is a "webhook endpoint" that's available to respond to API events. This request happens only once.
The GET request represents the "webhook request", where the API server makes GET requests to the webhook endpoint. These requests are on-going and regularly occurring as a result of service events.
The dotted arrow at the bottom is the webhook endpoint responding to the webhook request, and many API services treat responses with 2XX code as successful, whereas 4xx and 5xx response codes are unsuccessful. In the event of an unsuccessful webhook request then the API service will make multiple attempts at sending the webhook request.
For example:
* HN comment gets posted
* webhook endpoint receives GET request with related information (eg: user id, username, comment date, comment body)
* webhook endpoint responds with 2XX indicating success
Just above the diagram the author speaks about this:
"In addition to these operations, the subscription server may verify the intent of the subscriber by making an HTTP call to the provided callback with the same parameters requested before and an additional hub.challenge that must be echoed back by the subscriber."
PuSH solves a couple annoyances with webhooks that comes to my mind:
- Lack of debuggability: the inability to subscribe to events forces me to explicitly set up callback URL(s) on service providers' dashboards or in query strings in requests. IF I managed to set them up correctly, data will come crashing in any day in the future, throwing exceptions, or bouncing on unspecified routes. And all these POST catchers and local tunnels developers play with to get this right in the first place.
- Ad-hoc verification schemes: Every service comes up with their own way of ensuring the data originated from their servers. Signature hashes as 'X-*'-headers, a number of extra fields inside the JSON body, etc.
There are more, but these two has annoyed me for quite some time.