| Table of Contents |
|---|
Configure a Webhook
- Login to secure.ultracart.com and navigate to Home → Configuration → Development → Webhooks.
- Click the New Webhook button.
- Enter the Target URL. This is the full, absolute URL of your server. For this example, we entered https://www.myserver.com:9999/order_webhook.php
- API Version: Leave this at Latest Version if possible. If your webhook is mission critical, then specify a version to avoid changes.
- Authentication Type: For this example, we used no Authentication. You may configure Basic authentication if desired.
- Event Subscription: Select which events to receive for this webhook.
| Info |
|---|
|
- Add the expansion you need. The expansion is a csv list of which order parts you desire. For event_ship, you may only need the shipping part of an order. This reduces payload size considerably. The list of expansions are here: https://www.ultracart.com/api/#resource_order.html (you'll need to click on the Expansion link under the Order section in the left hand navigation).
- For this example, we added the kitchen sink.
affiliate,affiliate.ledger,auto_order,billing,buysafe,channel_partner,checkout,coupon,customer_profile,digital_order,edi,fraud_score,gift,gift_certificate,internal,item,linked_shipment,marketing,payment,payment.transaction,quote,salesforce,shipping,summary,taxes
- For this example, we added the kitchen sink.
- Message Payload: Configure Max Size and Max Events / Payload
- Click the Save button
- After saving, edit the webhook and add any expansions needed. See http://www.ultracart.com/api/ for expansion lists.
List of Webhooks
Webhook Expansions
| Tip |
|---|
Webhooks have expansions! They are only visible after you create the webhook. Once you create your webhook, edit it and add expansions to your events to ensure you get all the data you need.
|
...
- Find the target distribution center and click the edit button.
- Click on the
Transmission Mechanismtab when the distribution center loads. - Scroll down until you find the mechanism named
REST. Select that mechanism. - Select the API User and then the webhook.
- Save your changes.
Webhook Script Examples
The webhook will receive a JSON payload as a POST body. The structure of the payload is an array of simple objects with key = event_name and value = object.
Test your Webhook
Once your webhook script is deployed, test out your webhook by clicking the test button on the configuration screen. All webhooks have detailed logging accessible via the log button.
Sample JSON Payload
This webhook contains an order_create event. Note that all payloads are arrays of events, even those containing a single event.
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
[
{"order_create":
{
"merchant_id": "DEMO",
"order_id": "DEMO-0009103373",
"current_stage": "Shipping Department",
"creation_dts": "2016-04-07T14:07:36-04:00",
"language_iso_code": "ENG",
"billing": {
"first_name": "Test",
"last_name": "Order",
"address1": "Test Street",
"city": "ELK GROVE",
"state_region": "CA",
"postal_code": "95758",
"country_code": "US",
"email": "adam@kontor.hu"
},
"shipping": {
"weight": {
"value": 5,
"uom": "LB"
},
"shipping_method": "USPS: Priority Mail",
"first_name": "Test",
"last_name": "Order",
"address1": "Test Street",
"city": "ELK GROVE",
"state_region": "CA",
"postal_code": "95758",
"country_code": "US",
"ship_to_residential": true,
"day_phone": "(234) 234-2342",
"tracking_numbers": [
""
],
"lift_gate": false
},
"taxes": {
"tax_rate": 0.08000,
"tax_rate_state": 0.07250,
"tax_rate_city": 0.00750
},
"payment": {
"payment_method": "Credit Card",
"payment_status": "Processed",
"test_order": true,
"hold_for_fraud_review": false,
"credit_card": {
"card_type": "VISA",
"card_number": "1111",
"card_number_truncated": true,
"card_expiration_month": 12,
"card_expiration_year": 2018,
"card_auth_ticket": "TEST"
},
"payment_dts": "2016-04-07T14:07:36-04:00",
"transactions": [
{
"transaction_gateway": "WorldPay Business Gateway",
"transaction_timestamp": "2016-04-07T14:07:36-04:00",
"details": [
{
"name": "Authorization Code",
"value": "TEST",
"type": "AuthTicket"
},
{
"name": "Test Transaction",
"value": "Yes"
}
],
"successful": true
}
]
},
"summary": {
"shipping_handling_total": {
"value": 2.96,
"localized": 2.96,
"localized_formatted": "$2.96"
},
"subtotal": {
"value": 20.00,
"localized": 20.00,
"localized_formatted": "$20.00"
},
"tax": {
"value": 1.60,
"localized": 1.60,
"localized_formatted": "$1.60"
},
"total": {
"value": 24.56,
"localized": 24.56,
"localized_formatted": "$24.56"
},
"shipping_handling_total_discount": {
"value": 0.00,
"localized": 0.00,
"localized_formatted": "$0.00"
},
"subtotal_discount": {
"value": 0.00,
"localized": 0.00,
"localized_formatted": "$0.00"
},
"taxable_subtotal_discount": {
"value": 0.00,
"localized": 0.00,
"localized_formatted": "$0.00"
},
"taxable_subtotal": {
"value": 20.00,
"localized": 20.00,
"localized_formatted": "$20.00"
}
},
"internal": {
"exported_to_accounting": true
},
"marketing": {
"mailing_list": true
},
"items": [
{
"merchant_item_id": "Bone",
"quantity": 1,
"description": "TJ\u0027s DOGGIE BONES (5 lbs.)\nCode: JQXZPZWBFQ",
"cost": {
"value": 20.00,
"localized": 20.00,
"localized_formatted": "$20.00"
},
"weight": {
"value": 2.26796,
"uom": "KG"
},
"tax_free": false,
"special_product_type": "",
"free_shipping": false,
"discount": {
"value": 0,
"localized": 0.00,
"localized_formatted": "$0.00"
},
"item_reference_oid": 50786363,
"accounting_code": "Bone",
"length": {
"value": 0.394,
"uom": "IN"
},
"height": {
"value": 0.394,
"uom": "IN"
},
"width": {
"value": 0.394,
"uom": "IN"
},
"no_shipping_discount": false,
"ship_separately": false,
"distribution_center_code": "DFLT",
"hazmat": false,
"kit": false,
"kit_component": false,
"upsell": false,
"exclude_coupon": false,
"unit_cost_with_discount": {
"value": 20.00,
"localized": 20.00,
"localized_formatted": "$20.00"
},
"total_cost_with_discount": {
"value": 20.00,
"localized": 20.00,
"localized_formatted": "$20.00"
},
"cogs": 3.0000,
"barcode": "078742226583",
"country_code_of_origin": "US"
}
],
"customer_profile": {
"customer_profile_oid": 1971831,
"email": "adam@kontor.hu",
"track_separately": false,
"tax_exempt": false,
"allow_purchase_order": false,
"auto_approve_purchase_order": false,
"allow_cod": false,
"auto_approve_cod": false,
"free_shipping": false,
"unapproved": false,
"send_signup_notification": false,
"no_realtime_charge": false,
"allow_selection_of_address_type": false,
"exempt_shipping_handling_charge": false,
"no_free_shipping": false,
"allow_3rd_party_billing": false,
"no_coupons": false,
"suppress_buysafe": false,
"allow_quote_request": false
},
"checkout": {
"customer_ip_address": "79.121.124.98",
"custom_field7": "Y",
"screen_branding_theme_code": "CSTM",
"upsell_path_code": "DFLT"
},
"buysafe": {
"buysafe_shopping_cart_id": "0438358E58035D0153F1E70A59051600",
"buysafe_bond_available": false,
"buysafe_bond_free": false,
"buysafe_bond_wanted": true
}
}
}
] |
...