Skip to main content

 

Documentation & User Guides | FotoWare

Order Webhooks

Webhooks make it possible for third-party integrations to be notified and perform additional automated actions triggered by certain events in FotoWeb. The following events related to orders and the shopping cart can trigger webhooks:

  • Changes in the shopping cart
  • Submission of the shopping cart to an order
  • Approval of an order

Webhooks are triggered if they are enabled in the site configuration. If enabled, a webhook is triggered regardless whether the event was caused by an interactive user action or by an API request. Each webhook may individually be enabled or disabled.

Webhook Requests

When a webhook is triggered, the FotoWeb server makes a HTTP POST request to an URL that is specified in the site configuration. The body of the request contains information about the order that was submitted or approved or about the user's shopping cart. Depending on the configuration, the request body is sent in JSON format or URL-encoded form data.

It is recommended to use JSON webhooks, as they convey more information.

JSON Webhook Requests

If a webhook is configured to use JSON data, then the webhook request looks as follows:

POST webhook_url
Content-Type: application/json

with the following request body:

{
  "data": {...}
  "type": "order",
  "id": "0237d5cb-ebc7-4647-9a70-7c27bd3f5e9d",
  "created": "2016-12-12T14:18:49.915000Z"
}

where

Attribute

Type

Description

data Object Order representation of the customer's shopping cart or of the order
type String This is always "order".
id String A unique ID of the event that triggered the webhook
created ISO 8601 Date (String) Time (in UTC) at which the event occurred

The data attribute can be used to check the state of the shopping cart or order after the event has occurred. For example, it is a representation of the modified shopping cart or the submitted or approved order.

Form Data Webhook Requests

If a webhook is configured to use form data, then the webhook request looks as follows:

POST webhook_url
Content-Type: application/x-www-form-urlencoded

The request body is a key/value list in standard URL-encoded form data containing the following parameters. Most parameters are identical or similar in name to various JSON representations, and more information can be found in the links in the "See also" column:

Key

Description

See also

id A unique ID of the event that triggered the webhook  
href URL of the order Order representation
created Time when order was created Order representation
modified Time when order was last modified Order representation
state Current state of the order Order representation
expires Time when order expires, empty if it never expires Order representation
numOrderItems Number of items in the order  
orderReference A human-readable string that uniquely identifies the order on the site. Order representation
checkoutPageLocation URL of the custom checkout page. Order representation
adminComment Comment on this order by the administrator. Order representation
userComment Comment on this order by the customer. Order representation
user-href URL of the user (customer) User representation
user-username Username of the user (customer) User representation
user-firstName First name of the user (customer) User representation
user-initial Middle initial of the user (customer) User representation
user-lastName Last name of the user (customer) User representation
user-email Email address of the user (customer) User representation
user-title Title of the user (customer) User representation
user-organization Organization of the user (customer) User representation
user-streetAddress Street address of the user (customer), comma-separated User representation
user-city City of the user (customer) User representation
user-state State of the user (customer) User representation
user-zipCode ZIP code of the user (customer) User representation
user-country Country of the user (customer) User representation
user-phone Phone number of the user (customer) User representation
user-fax Because people who use URL-encoded form data also use fax machines User representation

Webhook Response

The webhook server should respond with a status code of 204 No Content. However, any status code in the range 200 - 299 is acceptable, including 200 OK. Any additional headers or response body will be ignored.

If webhook requests fail, e.g., due to network errors or due to the webhook server not responding, then webhook requests may be resent by FotoWeb. To make sure that a webhook request for the same event has not already been received, the id field can be used.

For example, if FotoWeb fails to send a webhook request for a "shopping cart changed" event for the first time, then it will try to send the same request again later. The id field will be the same. If the webhook server has already received the first request but (due to a crash or network error) could not send a response to FotoWeb, then it can ignore the second request.

  • Was this article helpful?