Webhooks: Use Webhooks to Import & Update Orders

Add webhooks to import and update orders

In This Article

Before We Begin General Guide Add Webhooks to Postsale Quick Tip Video 1 - Send a Test Webhook 2 - Map the Request to Postsale Helpful Tips Map The Request Order Section Unique Orders in Postsale Address Section Items Section Charges Section Notes Section Payment Section Shipment Section 3 - Automation, Name Your Store, Add a Logo, Store Address Information to Know

Webhooks allow you to send order information to Postsale when an event occurs in your sales channel, such as when a new order is placed or when an order is updated.

This article will guide you through how to add webhooks in Postsale. See our Webhooks: Manage Your Webhooks help article for information on how to edit your existing webhooks.

Before We Begin

Adding Webhooks is a premium feature requiring the Soar billing plan. Learn more about managing your Postsale account in our Frequently Asked Questions.
This article assumes that you have a general knowledge of using webhooks. It also assumes that:
- Your sales channel supports the ability to create webhooks.
- Order information from your sales channel can be sent as JSON when a new order is created or when an order is updated.
You can create as many webhooks as you need. For example, you may create one webhook to send newly created orders to Postsale, and a second to send order updates.
Webhooks can be used to send information to Postsale only. They cannot be configured to send information from Postsale back to your sales channel.

General Guide

This article uses a general example of adding a webhook to send order information to Postsale so that you can become familiar with the process. Creating webhooks in your specific sales channel may differ from the examples shown below.

Add Webhooks to Postsale

Quick Tip Video

Here's a Quick Tip video that quickly covers the information in the rest of this help article.

Real World Example

We would like to use webhooks to send new order data to Postsale when a new order is placed in our sales channel.

1 - Send a Test Webhook

Procedure: Settings > Store Settings

Go to Settings.
Select Store Settings.

Select Webhook.
Select the type of webhook security used by your sales channel from the Security drop-down menu. Then, enter the correct values for the type of security selected.

Select from:

Basic Auth: Specify the Username and Password to authenticate the request.
Header Value: Specify the header and header value used to authenticate the request.
HMAC: Specify the HMAC Header and HMAC Secret Key used to authenticate the request.
IP White List: List of IP addresses from which requests are allowed.

Click the Copy to Clipboard button to copy the Postsale webhook URL.
Open your sales channel admin in a new web browser window and create a new webhook.
The steps to create and the options available when creating a webhook will be specific to your sales channel. However, be sure to:
- Specify whether the event that triggers the request is when a new order is created or when an order is updated.
- Select JSON as the webhook format.
- Paste the URL you copied in step 5 into the new webhook.
Follow the steps for your sales channel to send a test to Postsale for the webhook you just created.
Switch back to Postsale. After a few moments a sample web request will display in the webhook window.
Click Next to begin mapping.

2 - Map the Request to Postsale

The next step is to map the information in the webhook request to the fields the data should be imported to in Postsale.

We recommend mapping at least one field before continuing to the next step. While it is possible to edit the map after saving the webhook, mapping the fields now ensures that the connection will be saved successfully.

Helpful Tips

Before you begin, here are a few tips that may prove helpful during the mapping process:

The mapping screen breaks the data down into separate categories (Order, Address, Items, Charges, and so on). When you expand a category, only the fields in Postsale that relate to that category are shown. This helps to organize and simplify the mapping process.
The categories of the mapping screen are broken into two columns:
- The fields in Postsale
- The elements included in the webhook request, selectable from the drop-down menu
The currently selected field name is highlighted to help you keep track of which field is currently being mapped.
The elements in the request that have been mapped and the elements that have not yet been mapped are clearly identified for you.

Map The Request

Expand and map each of the following sections.

Order Section

The Orders section defines general order information:

Unique Orders in Postsale

The Source and Number fields are used together to identify unique orders in Postsale. Both fields must be mapped for Postsale to successfully post updates to existing orders. If either the source field or the number field is not mapped, existing orders will not be updated. Instead, a new order will be created in Postsale.

Source: Identifies the sales channel/order source for the order.
When mapped, the Source and Number fields are used together to uniquely identify an order in Postsale.
Number: The order number/ID of the order. Used to uniquely identify orders in Postsale.
If the Number field is unmapped or if no order number is imported, Postsale will auto generate sequential order numbers for you.
Status: Identifies the status of the order. (shipped, not shipped, backordered, etc.)
Requested Shipping: Identifies the shipping method requested by your customer.
Date: The date the order was placed. If no date field is mapped, Postsale will use the date the order was imported.

Address Section

The Ship To and Bill To addresses are mapped together by default. Check the Map Bill To and Ship To Separately option to map them independently.

Mapping Name Fields

You can map either the Name field or the First Name and/or Last Name fields, depending on how information is sent to Postsale. For example:

Map the Name field if the first and last names are in the same field in your source file
Map the First Name and/or Last Name fields if the names are in separate fields in your file.

The map bill to and ship to separately checkbox is highlighted.

Items Section

Use the Items section to map the details of the items on your orders. There are two line item strategies available:

Map items in a collection: Use this option if all items on the order are contained in a single array.
Map items individually: Use this option if each item on the order is listed individually.

Select the correct option from the Item Mapping drop-down menu. Then, follow the steps below for the strategy that matches how your request is configured.

The item mapping dropdown is selected.

Map Items in a Collection

Map the Items Path to the array in your request that contains all of the item information.
Then, map the remaining fields in the Items section to the correct elements in your request.

Map Items Individually

Map items for the maximum number of line items on a single order. For example, if the largest order contains 3 different items, follow these steps to add and map three individual items:

Click the Add button.
Map the Postsale item fields to the correct elements in your request. Then, click Save.

Charges Section

Use the Charges section to map the details of the charges on your orders, such as Tax or Shipping. There are two strategies available:

Map charges in a collection: Use this option if all charges on the order are contained in a single array.
Map charges individually: Use this option if each charge on the order is listed individually.

Select the correct option from the Charge Mapping drop-down menu. Then, follow the steps below for the strategy that matches how your request is configured.

The charge mapping drop-down is expanded.

Map Charges in a Collection

Map the Charges Path to the array in your request that contains all of the charge information.
Then, map the remaining fields in the Charges section to the correct elements in your request.

Map Charges Individually

Click the Add button.
Map the following fields:
1. Description: Map to the field in your file that describes the additional charge on the order.
2. Amount: The amount of the additional charge.
Select the type of charge from the Type drop-down menu.
If no Type is selected, Postsale will attempt to identify and apply the correct charge type based upon the charge's Description.
Click Save.

Add as many charges as needed for the orders in your file.

Notes Section

Use the Notes section to map the details any notes associated with your orders. There are two strategies available:

Map notes in a collection: Use this option if all notes associated to the order are contained in a single array.
Map notes individually: Use this option if each note on the order is listed individually.

Select the correct option from the Note Mapping drop-down menu. Then, follow the steps below for the strategy that matches how your request is configured.

The note mapping is selected from the note mapping drop-down menu.

Map Notes in a Collection

Map the Notes Path to the array in your request that contains all of the note information.
Then, map the remaining fields in the Notes section to the correct elements in your request.

Map Notes Individually

Add a map for each note associated with your orders.

For example: If you have a thank you message to your customers and an internal note for each order, you will add two note mappings.

Click the Add button.
Map the Date and Content fields.
1. When the Date field is unmapped, Postsale assigns the current import date.
Click Save.

Payment Section

Use the Payment section to map the payments for orders in your source file.

Map the Name and Amount fields.

Name: Map to the column in your file that contains the payment type. (PayPal, Credit Card, etc.)
Amount: Map to the column containing the amount of the payments.

There are two strategies available when mapping additional payment details such as the last four digits of a credit card number, the credit card security code, etc.:

Map payment details in a collection: Use this option if all payments associated to the order are contained in a single array.
Map payments individually: Use this option if each payment on the order is listed individually.

Select the correct option from the Payments Mapping drop-down menu. Then, follow the steps below for the strategy that matches how your request is configured.

Map Payments in a Collection

Map the Payments Path to the array in your request that contains all of the payment information.
Then, map the remaining fields in the Notes section to the correct elements in your request.

Map Payment Details Individually

Click the Add button.
Map the Name and Value fields. Then, click Save.
The additional payment details are added.

Shipment Section

The Shipment section gives you the ability to map the shipment details for each order in your webhook request to the appropriate shipment fields in Postsale so that a shipment is automatically created for each order.

This has several, powerful advantages:

It saves time. You won't need to create a shipment for each order.
You can preview and select rates for each shipment as soon as the orders are added to Postsale.
Orders can be batch processed right away since each order is already configured with valid shipment details.

Available Shipment Fields

Formatting for Success

Imported shipment data must be formatted correctly in the JSON file in order for Postsale to import and post the data successfully. Review our Webhooks: Format Data for Success help article for details.

Fields marked with an asterisk (*) in the table below must be formatted correctly.

Table: Webhook Available Shipment Fields

The following shipment fields are available:

POSTSALE FIELD	DESCRIPTION
Carrier*	The shipping carrier to use for the shipment. (USPS, UPS, FedEx, etc.)
Service*	The shipping service to use for the shipment. (UPS Ground, USPS Ground Advantage, FedEx Ground, etc.)
Apply Insurance	Specifies if you want to apply Shipment Protection to the shipment. Valid values: yes no The default value is No when the field is left unmapped. When Yes is specified, the carrier's shipment protection will be added to the shipment based upon the shipping carrier selected for the shipment (USPS, UPS, FedEx).
Insurance Amount	Specifies the amount of insurance to apply to the shipment when Apply Insurance is Yes. Values for currency must be in whole number and decimal format 25.75 19.95
Confirmation	Determines if you wish for a shipment confirmation to be applied to the shipment. Valid values: delivery_confirmation no_signature_required signature adult_signature
Residential	Specifies if the Ship To address is residential. Valid values: yes no address_validation The default is No when the field is left unmapped.
Package Type*	Defines the type of package being used for the shipment.
Length	Specifies the length of the package Values must be in whole numbers and decimals 5 4.25
Width	Specifies the width of the package Values must be in whole numbers and decimals 5 4.25
Height	Specifies the height of the package Values must be in whole numbers and decimals 5 4.25
Dimensional Unit	Defines the unit of measure used for the dimensions. Valid values: in cm
Weight	Defines the weight of the shipment. Values must be in whole numbers and decimals 1 2.75
Weight Unit	Defines the unit of measure used for the weight. Valid values: lbs oz kg g

Shipment Package Mapping

Correctly mapping the package information allows Postsale to associate multiple packages with a single shipment. There are two strategies available when mapping package details (package type, dimensions, and weight) within the Shipment section.

Map packages in a collection: Use this option if all package information is contained in a single array.
Map packages individually: Use this option if each package listed individually.

Select the correct option from the Shipment Package Mapping drop-down menu. Then, follow the steps below for the strategy that matches how your request is configured.

The shipment package mappin gis being selected from the drop-down menu.

Map Shipments in a Collection

Map the Packages Path to the array in your request that contains all of the package information.
Then, map the remaining package fields to the correct elements in your request.

Map Packages Individually

Add a package map for the maximum number of packages associated with your orders.

Click the Add button.
Map the package fields. Then, click Save.
The package mappings are added.

Once all sections have been mapped, click the Next button to save your mapping and finish your setup.

3 - Automation, Name Your Store, Add a Logo, Store Address

Verify that you wish for Postsale to perform the following actions automatically. Then, click Next.

Snippet: Store Setup Automation Settings

When an order is first imported
- Set the order's status to [select the status from the drop-down menu]
  
  Enable this option to specify what the local status of the order should be set to when order's are imported for the first time. With this option disabled, the order's local status will be blank when imported.
When a shipment is processed
- Set the order's status to ‘Shipped’
  
  With this option enabled, Postsale will set the order's status to ‘Shipped’ when a label is created for the order.
When a shipment is voided
- Set the order's status to ‘Voided’
  
  With this option enabled, Postsale will set the order's status to ‘Voided’ when a shipment is voided for the order.

Enter a name for this webhook connection into the Store Name field.
(Optional) Click the Logo tile. Then, select an image file (png or jpg) from your computer.
- Postsale supports JPEG and PNG files with a recommended size of 3 MB or less.
- Larger image files will be reduced to the maximum file size of 3 megabytes when uploaded.
- The image will be uploaded and become the logo for your webhook connection.
- The logo will automatically display in Postsale templates that include a logo, such as the Invoice with Logo template.
- Learn about editing an image in Postsale

A logo has been added and is displayed.

(Optional) Click Add Store Address to add a unique Ship From address from this store.
Learn how to configure your Default Shipment settings so that the Store Address is automatically selected as the Ship From address for your shipments.

Once added, the Store Address is displayed.

Click Finish to save your webhook as a store connection in Postsale.

The store is added to Postsale and is displayed in the list of stores in the Store Settings menu.

Information to Know

The order source and order number are used together to identify unique orders in Postsale.
- When creating a webhook to update existing orders, be sure that the order source and order number fields are mapped correctly.
The webhook map can be edited at any time. This is useful when the data sent to Postsale in the webhook request has changed and needs to be mapped to fields in Postsale.

webhook webhooks add webhook import import orders orders