WebHooks

(NB: Not yet available)

Huddle offers facility for HTTP callbacks via a WebHooks mechanism. The specification that we adhere to can be found at https://github.com/cloudevents/spec/blob/v1.0.1/http-webhook.md.

Contents

• Delivery Target Requirements
• Subscription Creation - File Added to Folder
• Subscription Deletion

Delivery Target Requirements

To make use of our webhooks functionality you will need to provide an HTTP endpoint to receive notifications - hereafter referred to as the delivery target. There follow some important notes regarding delivery target behaviour.

Delivery target validation

As an abuse protection measure, during the subscription creation process (detailed below) an OPTIONS request will be sent to the delivery target, with WebHook-Request-Origin and WebHook-Request-Rate headers, like this:

OPTIONS /your-delivery-target/ HTTP/1.1
WebHook-Request-Origin: webhooks.huddle.net
WebHook-Request-Rate: 100
..other headers omitted for brevity..

For the subscription to be successfully created, the delivery target must respond with a success response (i.e. with status code 200-299) that contains a WebHook-Allowed-Origin header matching the requested origin (which will be webhooks.huddle.net or webhooks.huddle.com) or an asterisk (that indicates that webhook requests from any origin are permitted). Also, a WebHook-Allowed-Rate header must be included, either confirming the requested rate (in notifications per minute) or specifying a different value. For example:

HTTP/1.1 200 OK
WebHook-Allowed-Origin: *
WebHook-Allowed-Rate: 50
Allow: POST
..other headers omitted for brevity..

Notification request details

Notifications are POST requests, with content that will vary according to the target of the subscription. The details can be found below, in the subscription creation section.

Notification response consequences

The system may take actions depending on the response received from a notification:

• Success code (200-299): should be returned in the usual case, and will result in no specific action being taken.
• 429 Too Many Requests responses will be respected, but the system will also proactively attempt to respect a WebHook-Allowed-Rate header in the validation response. A Retry-After header included in the response will be respected. Also, if a WebHook-Allowed-Rate header is included in the 429 response, this rate will be respected going forwards.
• Other non-success codes: The system will retry a certain number of times, before giving up and disabling the subscription so that no further notification attempts are made. Disabled subscriptions can be re-enabled by recreating them. NB: this scenario includes redirect codes (300-399) - webhook notifications will not follow redirections.

Subscription Creation - File Added to Folder

A subscription to receive a notification whenever a file is added to a folder (either by creation or by being moved or copied) can be created as follows:

POST /webhooks/subscriptions/folder/{folderId}/fileadded HTTP/1.1
Authorization: OAuth2 frootymcnooty/vonbootycherooty
..other headers omitted for brevity..

{
  “deliveryTargetUri”: “https://api.example.com/your-delivery-target/”,
  “deliveryTargetSecret”: “Basic 4398hfubf54:dkcjbwekfj”
}

..where {folderId} is the ID of the folder to subscribe to, deliveryTarget is the URI of the delivery target, and deliveryTargetSecret is optional - but will be used as the value of the Authorization header of all requests sent to the delivery target if provided.

Note that:

• The authenticated user must have read access to the folder in question to be permitted to subscribe. If this permission is lost after the subscription is created, notifications will no longer be sent.
• Only the folder itself will be watched, not the subfolders thereof.

The response in the default success scenario will be 201 Created:

HTTP/1.1 201 Created
Location: https://api.huddle.net/webhooks/subscriptions/1234

Other possible response codes include:

Response Code	Meaning
204	an identical but disabled subscription was found and re-enabled. A Location header will be included.
400	The request content was invalid or delivery target validation failed (see above).
401	No authentication information was provided.
403	The authenticated user does not have read access to the requested folder.
404	The requested folder does not exist.
409	an identical active subscription already exists. A Location header will be included.

Notifications for file added to folder events look like this:

POST /your-delivery-target/ HTTP/1.1
..headers omitted for brevity..

{
    link: {
        rel: “Folder.FileAdded”,
        href: “https://api.huddle.net/files/folders/1234/files/documents/5678”
    }
}

..where the href is the URI of document added to the folder.

Subscription Deletion

Subscriptions can be deleted by sending a DELETE request to the Location returned by the subscription creation request. For example:

DELETE /webhooks/subscriptions/{subscriptionId} HTTP/1.1
Authorization: OAuth2 frootymcnooty/vonbootycherooty
..other headers omitted for brevity..

The authenticated user must be the same as the user that created the subscription.

The response in the default success scenario will be 204 No Content. Other possible response codes include:

Response Code	Meaning
401	No authentication was provided
403	The subscription was not created by the authenticated user
404	The subscription does not exist