49 lines
2 KiB
Markdown
49 lines
2 KiB
Markdown
Open Photo API / Create/Subscribe to Webhook
|
|
=======================
|
|
#### OpenPhoto, a photo service for the masses
|
|
|
|
----------------------------------------
|
|
|
|
1. [Purpose][purpose]
|
|
1. [Endpoint][endpoint]
|
|
1. [Parameters][parameters]
|
|
|
|
----------------------------------------
|
|
|
|
<a name="purpose"></a>
|
|
### Purpose of the POST Webhook create API
|
|
|
|
Use this API to create a new webhook for a user.
|
|
|
|
This API differs from our others in that it's both interactive and does not return a [Standard Envelope][Envelope]. These are the steps required to complete a webhook subscription.
|
|
|
|
<a name="verification"></a>
|
|
|
|
1. The consumer _(you)_ makes a POST request to the provider _(the API host)_ to `http://apihost.com/webhook/subscribe` with the <a href="#">required parameters</a>.
|
|
1. The provider makes a GET request back to your `callback` URL passing along a `mode`, `topic`, and `challenge` parameter. A `verifyToken` parameter is passed back if originally supplied.
|
|
1. The consumer must validate that the subscription was intended (typically using the `verifyToken`) and print out the `challenge` value with a HTTP 200 response code.
|
|
1. If the consumer response is a HTTP 200 and the content body was equal to `challenge` then the provider completes the subscription.
|
|
|
|
----------------------------------------
|
|
|
|
<a name="endpoint"></a>
|
|
### Endpoint
|
|
|
|
_Authentication: required_
|
|
|
|
POST /webhook/subscribe
|
|
|
|
<a name="parameters"></a>
|
|
### Parameters
|
|
|
|
1. callback (required), A URL to POST to. This also needs to handle GET calls for the <a href="#verification">verification process</a>.
|
|
1. topic (required), _i.e. photo.upload_ - The topic which you'd like to subscribe to.
|
|
1. mode (required), Only _sync_ is supported at this time.
|
|
1. verifyToken (optional), A provider generated string to which is passed back as part of the <a href="#verification">verification process</a>.
|
|
|
|
----------------------------------------
|
|
|
|
[Envelope]: Envelope.markdown
|
|
[purpose]: #purpose
|
|
[endpoint]: #endpoint
|
|
[parameters]: #parameters
|