photo-documentation/docs/api/PostWebhookSubscribe.markdown

Create/Subscribe to Webhook

---

1. Purpose
2. Endpoint
3. Parameters

---

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. These are the steps required to complete a webhook subscription.

1. The consumer (you) makes a POST request to the provider (the API host) to http://apihost.com/webhook/subscribe with the required parameters.
2. 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.
3. 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.
4. If the consumer response is a HTTP 200 and the content body was equal to challenge then the provider completes the subscription.

---

Endpoint

Authentication: required

POST /webhook/subscribe

Parameters

1. callback (required), A URL to POST to. This also needs to handle GET calls for the verification process.
2. topic (required), i.e. photo.upload - The topic which you'd like to subscribe to.
3. mode (required), Only sync is supported at this time.
4. verifyToken (optional), A provider generated string to which is passed back as part of the verification process.

---