WebHooks.markdown

Examples demonstrating how RESTful WebHooks could work.

Doing it this way affords the following possibilities:

• You can direct your subscription requests to any URL you want.
• Handle all subscription management requests on a single URL on your server, or
• Handle subscription management requests on a unique URL per resource.
• Outsource your webhook subscriptions even to another server or domain, if you wish.

---

View all the posts (normal browser request):

===>
  GET /posts
  Host: example.com

<===
  200 Ok
  X-WebHooks-Allow: text/json, text/xml, rss/xml, atom/xml
  X-WebHooks-Help: /web-hooks/help?from=posts
  X-WebHooks-Events: CREATED, ACCESSED, UPDATED, DELETED
  X-WebHooks-Location: /posts/hooks

  ...the posts body...

---

See if /posts supports WebHook subscription:

===>
  HEAD /posts
  Host: example.com

<===
  200 Ok
  X-WebHooks-Allow: application/json, application/xml, rss/xml, atom/xml
  X-WebHooks-Help: /web-hooks/help?from=posts
  X-WebHooks-Events: CREATED, ACCESSED, UPDATED, DELETED
  X-WebHooks-Location: /posts/hooks

• X-WebHooks-Location is required
• X-WebHooks-Events is required
• We can infer the X-WebHooks-Allow from the regular Allow header, if the X-WebHooks-Allow is not present.

---

To subscribe:

===>
  POST /posts/hooks
  Host: example.com
  X-WebHooks-Accept: application/json
  Content-Type: application/x-www-form-urlencoded
  
  event=UPDATED&callback_url=http://hookscripts.com/script/run/28371&resource_url=http://example.com/posts

<===
  201 Created
  Location: /posts/hooks/a38vp-q98hq-p28v3-98q3y

• The X-WebHooks-Accept header is required.

---

To view your subscription:

===>
  GET /posts/hooks/a38vp-q98hq-p28v3-98q3y
  Host: example.com
  Accept: application/xml

<===
  200 OK
  Content-Type: application/xml
  Content-Length: ##
  
  <hook>
    <event>UPDATED</event>
    <callback_url>http://hookscripts.com/script/run/28371</callback_url>
    <resource_url>http://example.com/posts</resource_url>
    <accept>application/json</accept>
    <stats>
      <event-count>39</event-count>
      <average-duration>1219ms</average-duration>
      <last-event>2009-10-21 10:06:42PM</last-event>
      <response-log>/posts/hooks/a38vp-q98hq-p28v3-98q3y.log</response-log>
    </stats>
  </hook>

---

To modify your subscription:

There is no need to define how to modify a subscription. You can always simply unsubscribe, then re-subscribe.

---

To delete your subscription:

===>
  DELETE /posts/hooks/a38vp-q98hq-p28v3-98q3y

<===
  202 Accepted

The way I'm thinking of a subscription, it can be bound to any number of event(s), but when it is deleted, it's simply gone. No specifying which event(s) to unsubscribe. It might also be nice to be able to delete all subscriptions to a specific hook end-point (URL, SMS, etc). Might do something like:

DELETE /posts/hooks?callback_url=<URI>

or

DELETE /posts/hooks?resource_url=<URI>

---

Further notes:

I'd like to add a list of recommended options:

• retry preference (should the hook be re-tried if first attempt fails?)
• timeliness preference (do I care if it's a minute or two late, or do I need it ASAP?)
• include resource in payload?
• expiration?
• notification frequency throttling?