Webhook

A Webhook is a tool for retrieving and storing data from a certain event. It allows you to register an http:// or https:// URL where the event data can be stored in JSON or XML formats. Webhooks can be registered for the following events:

App
uninstalled
Carts
create/update
Checkouts
create/delete/update
Collections
create/update/delete
Customer groups
create/update/delete
Customers
create/delete/disable/enable/update
Disputes
create/update
Fulfillments
create/update
Orders
create/delete/updated/paid/cancelled/fulfilled/partially_fulfilled
Order transactions
create
Products
create/update/delete
Refunds
create
Shop
update

What can you do with Webhook?

The haravan API lets you do the following with the Webhook resource. More detailed versions of these general actions may be available:

Webhook Properties

address
{ "address" : "http://apple.com/uninstall" }

The URI where the webhook should send the POST request when the event occurs.

created_at
{ "created_at" : "2012-09-28T11:50:07-04:00" }

The date and time when the webhook was created. The API returns this value in ISO 8601 format.

fields
{ "fields" : ["id", "updated_at"] }

(Optional) An array of fields which should be included in webhooks.

format
{ "format" : "xml" }

The format in which the webhook should send the data. Valid values are json and xml.

id
{ "id" : "901431826" }

The unique numeric identifier for the webhook.

metafield_namespaces
{ "metafield_namespaces" : ["google", "inventory"] }

(Optional) An array of namespaces for metafields that should be included in webhooks.

topic
{ "topic" : "app/uninstalled" }

The event that will trigger the webhook. Valid values are: orders/create, orders/delete, orders/updated, orders/paid, orders/cancelled, orders/fulfilled, orders/partially_fulfilled, order_transactions/create, carts/create, carts/update, checkouts/create, checkouts/update, checkouts/delete, refunds/create, products/create, products/update, products/delete, collections/create, collections/update, collections/delete, customer_groups/create, customer_groups/update, customer_groups/delete, customers/create, customers/enable, customers/disable, customers/update, customers/delete, fulfillments/create, fulfillments/update, shop/update, disputes/create, disputes/update, app/uninstalled

updated_at
{ "updated_at" : "2012-09-28T11:50:07-04:00" }

The date and time when the webhook was updated. The API returns this value in ISO 8601 format.

Endpoints

GET/admin/webhooks.json
address

Use this parameter to retrieve only webhooks that possess the URI where the webhook sends the POST request when the event occurs.

created_at_max

Use this parameter to retrieve only webhooks that were created <b>before</b> a given date and time (format: 2008-12-31 03:00).

created_at_min

Use this parameter to retrieve only webhooks that were created <b>after</b> a given date and time (format: 2008-12-31 03:00).

fields

A comma-separated list of the properties you want returned for each item in the result list. Use this parameter to restrict the returned list of items to showing only those properties you specify.

limit

The maximum number of webhooks that should be returned. Setting this parameter outside the maximum range will result in an error.

(default: 50) (maximum: 250)
page

The page number of the result list to retrieve. Use this in tandem with limit to page through the webhooks in a shop.

(default: 1)
since_id

Use this parameter to restrict the returned list to only webhooks whose id is <b>greater</b> than the specified id.

topic

Show webhooks with a given topic. Valid topics are: orders/create, orders/delete, orders/updated, orders/paid, orders/cancelled, orders/fulfilled, orders/partially_fulfilled, order_transactions/create, carts/create, carts/update, checkouts/create, checkouts/update, checkouts/delete, refunds/create, products/create, products/update, products/delete, collections/create, collections/update, collections/delete, customer_groups/create, customer_groups/update, customer_groups/delete, customers/create, customers/enable, customers/disable, customers/update, customers/delete, fulfillments/create, fulfillments/update, shop/update, disputes/create, disputes/update, app/uninstalled

updated_at_min

Use this parameter to retrieve only webhooks that were updated <b>before</b> a given date and time (format: 2008-12-31 03:00).

updated_at_max

Use this parameter to retrieve only webhooks that were updated <b>after</b> a given date and time (format: 2008-12-31 03:00).

Get a list of all webhooks for your shop.

GET /admin/webhooks.json
View Response
HTTP/1.1 200 OK
{
  "webhooks": [
    {
      "address": "http:\/\/apple.com",
      "created_at": "2015-03-28T13:31:19-04:00",
      "fields": [
      ],
      "format": "json",
      "id": 4759306,
      "metafield_namespaces": [
      ],
      "topic": "orders\/create",
      "updated_at": "2015-03-28T13:31:19-04:00"
    },
    {
      "address": "http:\/\/apple.com\/uninstall",
      "created_at": "2015-03-28T13:31:19-04:00",
      "fields": [
      ],
      "format": "json",
      "id": 901431826,
      "metafield_namespaces": [
      ],
      "topic": "app\/uninstalled",
      "updated_at": "2015-03-28T13:31:19-04:00"
    }
  ]
}

Get a list of all webhooks for your shop after a specified ID

GET /admin/webhooks.json?since_id=4759306
View Response
HTTP/1.1 200 OK
{
  "webhooks": [
    {
      "address": "http:\/\/apple.com\/uninstall",
      "created_at": "2015-03-28T13:31:19-04:00",
      "fields": [
      ],
      "format": "json",
      "id": 901431826,
      "metafield_namespaces": [
      ],
      "topic": "app\/uninstalled",
      "updated_at": "2015-03-28T13:31:19-04:00"
    }
  ]
}
GET/admin/webhooks/count.json
address

Use this parameter to retrieve only webhooks that possess the URI where the webhook sends the POST request when the event occurs.

topic

Show webhooks with a given topic. Valid topics are: orders/create, orders/delete, orders/updated, orders/paid, orders/cancelled, orders/fulfilled, orders/partially_fulfilled, order_transactions/create, carts/create, carts/update, checkouts/create, checkouts/update, checkouts/delete, refunds/create, products/create, products/update, products/delete, collections/create, collections/update, collections/delete, customer_groups/create, customer_groups/update, customer_groups/delete, customers/create, customers/enable, customers/disable, customers/update, customers/delete, fulfillments/create, fulfillments/update, shop/update, disputes/create, disputes/update, app/uninstalled

Count all of the webhooks for your shop.

GET /admin/webhooks/count.json
View Response
HTTP/1.1 200 OK
{
  "count": 2
}

Count all of the webhooks for topic 'orders/create'

GET /admin/webhooks/count.json?topic=orders/create
View Response
HTTP/1.1 200 OK
{
  "count": 1
}
GET/admin/webhooks/4759306.json

Get a single webhook

fields

A comma-separated list of the properties you want returned for each item in the result list. Use this parameter to restrict the returned list of items to showing only those properties you specify.

Get a single webhook by its id.

GET /admin/webhooks/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "webhook": {
    "address": "http:\/\/apple.com",
    "created_at": "2015-03-28T13:31:19-04:00",
    "fields": [
    ],
    "format": "json",
    "id": 4759306,
    "metafield_namespaces": [
    ],
    "topic": "orders\/create",
    "updated_at": "2015-03-28T13:31:19-04:00"
  }
}
POST/admin/webhooks.json

Every webhook needs a topic and an address. Failure to have a topic or an address will result in a 422 - Unprocessable Entity error.

format

Use this parameter to select the format to recieve the data in. Valid values are json and xml.

(default: json)

After installing a haravan App, it’s a pain for shop owners to have to manually install webhooks the app needs. Automate that by using this API call.

POST /admin/webhooks.json
{
  "webhook": {
    "topic": "orders\/create",
    "address": "http:\/\/whatever.hostname.com",
    "format": "json"
  }
}
View Response
HTTP/1.1 201 Created
{
  "webhook": {
    "address": "http:\/\/whatever.hostname.com",
    "created_at": "2015-03-28T13:33:43-04:00",
    "fields": [
    ],
    "format": "json",
    "id": 987911556,
    "metafield_namespaces": [
    ],
    "topic": "orders\/create",
    "updated_at": "2015-03-28T13:33:43-04:00"
  }
}

Trying to create a webhook without an address or topic will return an error

POST /admin/webhooks.json
{
  "webhook": {
    "body": "foobar"
  }
}
View Response
HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "topic": [
      "can't be blank",
      "Invalid topic specified. Topics allowed: orders\/create, orders\/delete, orders\/updated, orders\/paid, orders\/cancelled, orders\/fulfilled, orders\/partially_fulfilled, order_transactions\/create, carts\/create, carts\/update, checkouts\/create, checkouts\/update, checkouts\/delete, refunds\/create, products\/create, products\/update, products\/delete, collections\/create, collections\/update, collections\/delete, customer_groups\/create, customer_groups\/update, customer_groups\/delete, customers\/create, customers\/enable, customers\/disable, customers\/update, customers\/delete, fulfillments\/create, fulfillments\/update, shop\/update, disputes\/create, disputes\/update, app\/uninstalled"
    ],
    "address": [
      "can't be blank"
    ]
  }
}
PUT/admin/webhooks/4759306.json

Update a webhook's topic and/or address URIs.


Change a webhook so that it POSTs to a different address:

PUT /admin/webhooks/#{id}.json
{
  "webhook": {
    "id": 4759306,
    "address": "http:\/\/somewhere-else.com"
  }
}
View Response
HTTP/1.1 200 OK
{
  "webhook": {
    "address": "http:\/\/somewhere-else.com",
    "created_at": "2015-03-28T13:31:19-04:00",
    "fields": [
    ],
    "format": "json",
    "id": 4759306,
    "metafield_namespaces": [
    ],
    "topic": "orders\/create",
    "updated_at": "2015-03-28T13:33:44-04:00"
  }
}
DELETE/admin/webhooks/4759306.json

Delete a webhook


Remove an existing webhook from a shop

DELETE /admin/webhooks/#{id}.json
View Response
HTTP/1.1 200 OK
{}