API Webhook - Revision history

Admin at 04:30, 6 June 2018

2018-06-06T04:30:31Z

Admin: /* DELETE /api/webhooks/WEBHOOK_ID.json */

2018-06-06T04:27:05Z

DELETE /api/webhooks/WEBHOOK_ID.json

Admin: /* PUT /admin/webhooks/4759306.json */

2018-06-06T04:25:55Z

PUT /admin/webhooks/4759306.json

Admin: /* POST /api/webhooks.json */

2018-06-06T04:22:03Z

POST /api/webhooks.json

Admin: /* GET /admin/webhooks/4759306.json */

2018-06-06T04:15:48Z

GET /admin/webhooks/4759306.json

Admin: /* Get a single webhook by its id. */

2018-06-06T04:15:18Z

Get a single webhook by its id.

Admin: /* Count all of the webhooks for your shop. */

2018-06-06T04:10:34Z

Count all of the webhooks for your shop.

Admin: /* Example Request and Response */

2018-06-06T04:10:11Z

Example Request and Response

Admin: /* Example Request and Response */

2018-06-06T04:09:23Z

Example Request and Response

Admin: /* Optional Parameters */

2018-06-06T04:06:37Z

Optional Parameters

← Older revision		Revision as of 04:30, 6 June 2018
Line 8:		Line 8:

	API Webhooks should not be confused with our older, limited Notification Webhooks. The Notification Webhooks are designed to only provide a simple order notification service, whereas API Webhooks can be registered on a much wider range of events.		API Webhooks should not be confused with our older, limited Notification Webhooks. The Notification Webhooks are designed to only provide a simple order notification service, whereas API Webhooks can be registered on a much wider range of events.
		+
		+	== Using Webhooks ==
		+
		+	A Webhook allows you to register an ''http://'' or ''https://'' URL with the associated event data being stored in either JSON or XML formats.
		+
		+	Webhooks are most commonly triggered when
		+
		+	* An order is placed and you want to notify your shipping agents
		+	* A product's price is changed
		+	* A new product is created in order to update social media platforms
		+	* An order is paid so that your accounting software can be updated
		+
		+	== Webhook events ==
		+
		+	You can register a webhook for the following events
		+
		+	; Customers : creation/deletion/disable/update
		+	; Orders : creation/payment
		+
		+	Further Webhook events will be added in the near future.
		+
		+	== Managing Webhooks ==
		+
		+	<gallery heights="200px" widths="200px" class="right">
		+	File:webhooks1.jpg\|Managing Webhooks
		+	</gallery>
		+
		+	Webhooks can be created and managed on the 'Accounts -> API Webhooks' page.
		+
		+	You can create, edit and delete Webhooks on this page. Any Webhooks created using this interface are listed as having a ''Manual'' source.
		+
		+	When you create a Webhook, you need to specify which event you are trying to register the webhook for, the format of the event data being either JSON or XML and finally the callback URL which needs to be posted when the event occurs.
		+
		+	Webhooks can also be created through the API, and these will be listed in the interface, but you cannot edit or delete them. They can only be managed through the API interface. In some cases, applications can supply a name for the webhook, so that you can easily identify the source of the webhook registration.

	== Anatomy of a Webhook ==		== Anatomy of a Webhook ==

@@ Line 1,568: / Line 1,568: @@
 === <code>DELETE /api/webhooks/WEBHOOK_ID.json</code> ===
-Delete a webhook
+Delete a webhook.
-Remove an existing webhook from a store
+==== Example Request and Response ====
-<code>DELETE /admin/webhooks/#{id}.json</code>
+<pre>
-===== Response=====
+HTTP/1.1 200 OK
 {}
 </pre>

@@ Line 1,536: / Line 1,536: @@
 </pre>
-===PUT /admin/webhooks/4759306.json===
+=== <code>PUT /api/webhooks/WEBHOOK_ID.json</code> ===
-Update a webhook's topic and/or address URIs.
+Update a webhook subscription's topic or address URIs.
-Change a webhook so that it POSTs to a different address:
+==== Example Request and Response ====
-<code>PUT /admin/webhooks/#{id}.json</code>
+<pre>
+{
    "webhook": {
      "id": 4759306,
-     "address": "http:\/\/somewhere-else.com\/"
+     "address": "https://somewhere-else.com/"
+   }
+}
 HTTP/1.1 200 OK
+{
    "webhook": {
      "id": 4759306,
-     "address": "http:\/\/somewhere-else.com\/",
+     "address": "http://somewhere-else.com/",
-     "topic": "orders\/create",
+     "topic": "orders/create",
      "created_at": "2017-03-20T16:02:17-04:00",
      "updated_at": "2017-03-20T16:04:29-04:00",
-     "format": "json",
+     "format": "json"
+   }
+}

@@ Line 1,507: / Line 1,507: @@
 === <code>POST /api/webhooks.json</code> ===
-Every webhook needs a topic and an address. Failure to have a topic or an address will result in a 422 - Unprocessable Entity error.
+Create a webhook subscription by specifying both an address and a topic. This API call can be used by apps to install any notifications that the app needs.
-{| class="reference"
+==== Example Request and Response ====
+{
    "webhook": {
-     "topic": "orders\/create",
+     "topic": "orders/create",
-     "address": "http:\/\/whatever.hostname.com\/",
+     "address": "https://whatever.hostname.com/",
      "format": "json"
+   }
+}
-====Response====
+HTTP/1.1 201 Created
+{
    "webhook": {
      "id": 1047897619,
-     "address": "http:\/\/whatever.hostname.com\/",
+     "address": "http://whatever.hostname.com/",
-     "topic": "orders\/create",
+     "topic": "orders/create",
      "created_at": "2017-03-20T16:02:33-04:00",
      "updated_at": "2017-03-20T16:02:33-04:00",
-     "format": "json",
+     "format": "json"
+   }
+}

@@ Line 1,474: / Line 1,474: @@
 GET /api/webhooks/count.json?topic=orders/create
 </pre>
 === <code>GET /api/webhooks/WEBHOOK_ID.json</code> ===

@@ Line 1,485: / Line 1,485: @@
-====Get a single webhook by its id.====
+=== <code>GET /api/webhooks/WEBHOOK_ID.json</code> ===
-<code>GET /admin/webhooks/#{id}.json</code>
+Retrieves a single webhook by ID.
 <pre>
 HTTP/1.1 200 OK
+{
    "webhook": {
-     "id": 4759306,
+     "id": 248,
-     "address": "http:\/\/apple.com",
+     "address": "https://mytestapps.com.au/webhooks/app_uninstalled",
-    "topic": "orders\/create",
+     "created_at": "2016-10-13T16:16:52.210+11:00",
-     "created_at": "2017-03-20T16:02:17-04:00",
+     "updated_at": "2016-10-13T16:16:52.210+11:00",
      "format": "json",
-     "fields": [
+     "topic": "app/uninstalled"
+   }
+}
 </pre>
 === <code>POST /api/webhooks.json</code> ===

← Older revision		Revision as of 04:10, 6 June 2018
Line 1,473:		Line 1,473:

	GET /api/webhooks/count.json?topic=orders/create		GET /api/webhooks/count.json?topic=orders/create
−	~~</pre>~~
−
−	~~====Count all of the webhooks for your shop.====~~
−
−	~~<code>GET /admin/webhooks/count.json</code>~~
−
−	~~<pre>~~
−	~~HTTP/1.1 200 OK~~
−	{
−	~~"count": 25~~
−	}
	</pre>		</pre>

@@ Line 1,419: / Line 1,419: @@
+   ]
+}
 Examples using filters
@@ Line 1,426: / Line 1,425: @@
 GET /api/webhooks.json?since_id=4759306
 === <code>GET /api/webhooks/count.json</code> ===

@@ Line 1,462: / Line 1,462: @@
 <pre>
-GET /api/blogs/BLOG_ID/articles/count.json
+GET /api/webhooks/count.json
-{| class="reference"
-! address
+  "count": 15
-|Use this parameter to retrieve only webhooks that possess the URI where the webhook sends the POST request when the event occurs.
-====Count all of the webhooks for topic 'orders/create'====
+Examples using filters
-<code>GET /admin/webhooks/count.json?topic=orders/create</code>
+GET /api/webhooks/count.json?topic=orders/create
 </pre>

@@ Line 1,437: / Line 1,437: @@
 |Limit the results to only include objects which have an id greater than the given value.
 |-
-!title
+!address
-|Limit the results to only include articles with the given title.
+|Limit the results to only include webhooks with the given address (URI).
 |-
-!handle
+!topic
-|Limit the results to only include articles with the given handle.
+|Limit the results to only include webhooks with the given topic.
 |-
-!author
+!source
-|Limit the results to only include articles written by the given author.
+|Limit the results to only include webhooks with the given source.
 |-
 !created_at_min
-|Return only the articles created after the given date and time. Use the format "2014-12-31 12:00".
+|Return only the webhooks created after the given date and time. Use the format "2014-12-31 12:00".
 |-
 !created_at_max
-|Return only the articles created before the given date and time. Use the format "2014-12-31 12:00".
+|Return only the webhooks created before the given date and time. Use the format "2014-12-31 12:00".
 |-
 !updated_at_min
-|Return only the articles updated after the given date and time. Use the format "2014-12-31 12:00".
+|Return only the webhooks updated after the given date and time. Use the format "2014-12-31 12:00".
 |-
 !updated_at_max
-|Return only the articles updated before the given date and time. Use the format "2014-12-31 12:00".
+|Return only the webhooks updated before the given date and time. Use the format "2014-12-31 12:00".
 |}