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 of whether the event was caused by an interactive user action or by an API request. Each webhook may individually be enabled or disabled.
Note: Using webhooks requires an API license.
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.