Understand webhooks
Oracle Commerce includes two types of webhooks, asynchronous event webhooks and synchronous function webhooks:
- Event webhooks are asynchronous; they are triggered by JMS (Java Message Service) events. An event webhook call returns an HTTP status code. An event webhook request can be sent to multiple URLs.
- Function webhooks are synchronous; they are invoked explicitly in code. A successful function webhook call returns JSON data. A function webhook request can be sent to only one URL.
Both types of webhooks are described below.
Understand event webhooks
An event webhook sends a POST request to URLs you specify each time a Commerce event occurs. The body of the request contains the data associated with the event, in JSON format. The external system that receives the POST request returns an HTTP status code indicating whether the data was received successfully. A 200-level status code indicates the POST was successful. Any other code indicates failure; if this occurs, Commerce sends the POST request again. The webhook is executed up to five times until it succeeds or gives up.
The external system can use the data from the webhook request body in requests to the endpoints of the Commerce REST API endpoints. For example, you can configure the Order Submit webhook to send a notification to your order management system (OMS) every time a shopper successfully submits an order. When a change occurs to an order in the OMS, the OMS can issue a PUT request to the Update Order endpoint to modify the order in Commerce.
Commerce includes the following event webhooks:
| Webhook | Notification event |
|---|---|
| Account Create | A new account was successfully created by an administrator. See Configure Business Accounts for more information. |
| Account Update | An existing account was successfully updated by an administrator. See Configure Business Accounts for more information. |
| Cart Idle | A cart that contains items has been inactive for the number of minutes you specify on the Abandoned Cart Settings page. See Configure Abandoned Cart settings for more information. |
| Export Complete | A data export process successfully completed. |
| Import Complete | A data import process successfully completed. |
| Inventory Update | Out-of-stock SKUs are back in stock.
See Understand inventory for information about inventory data that determines whether a SKU is in stock. |
| Order Cancel | An agent canceled an order. |
| Order Cancel Without Payment Details |
An agent canceled an order. The body for this webhook does not include payment details. See Understand webhooks and PCI DSS compliance for more information. |
| Order Submit | An order was successfully submitted by a customer or an agent. |
| Order Submit Without Payment Details |
An order has been successfully submitted by a customer or an agent. The body for this webhook does not include payment details. See Understand webhooks and PCI DSS compliance for more information. |
| Publish Complete | Changes were successfully published. |
| Remorse Period Start |
An order’s customer remorse period has started. See Set the customer remorse period for more information. |
| Remorse Period Start Without Payment Details |
An order’s customer remorse period has started. See Set the customer remorse period for more information. The body for this webhook does not include payment details. See Understand webhooks and PCI DSS compliance for more information. |
| Return Request Update | A return request was successfully processed by an agent. |
| Return Request Update without Payment Details |
A return request was successfully processed by an agent. The body for this webhook does not include payment details. See Understand webhooks and PCI DSS compliance for more information. |
| Shopper Profile Create | A new shopper registered on your instance. |
| Shopper Profile Update | A registered shopper changed their account details. |
| Shopper Profile Delete | A registered shopper’s account has been deleted. See Delete Shopper Information for more information. |
| Order Redact | An order’s properties have been redacted. See Delete Shopper Information for more information. |
| Request Quote | A shopper requested a quote for an order on a store that supports an external product configurator. |
| Update Quote | A shopper accepted or rejected a quote, or the quote was canceled on a store that supports an external product configurator. |
| Account Request | An account-based shopper has submitted an account registration request. See Configure Business Accounts for more information. |
| Contact Request | An account-based shopper or anonymous shopper has submitted a contact registration request. See Configure Business Accounts for more information. |
Understand function webhooks
Like an event webhook, a function webhook sends a JSON notification to a URL you specify each time something happens on your store. For example, you can configure the Shipping Calculator webhook to send a notification to an external shipping service every time a shopper requests shipping costs for an order.
While an external system only sends an HTTP status code in response to an event webhook POST request, a system must respond to a function webhook POST request with information in JSON format. You must implement the external system’s API to write code that processes the request and sends a response to Commerce. For example the Shipping Calculator webhook expects a set of shipping methods and their prices, which are displayed to the shopper who has requested them.
Commerce includes the following function webhooks:
| Webhook | Description |
|---|---|
| Shipping Calculator | Integrates shipping services (such as UPS, USPS, or FedEx) into your store. See Integrate with External Shipping Calculators for more information. |
| Credit Card Payment | Integrates custom payment gateways that let your store accept credit card payments. See Create a Credit Card Payment Gateway Integration for more information. |
| Generic Payment | Integrates custom payment gateways that let your store accept various payment types. See Create a Generic Payment Gateway Integration for more information. |
| External Price Validation | Validates prices with an external pricing system. See Integrate with an External Pricing System for more information. |
| External Tax Calculation | Integrates tax processors that calculate sales tax in the shopping cart. See Configure Tax Processors for more information. |
| Order Approvals | Integrates systems that determine if an order placed on an account-based store requires approval. See Integrate with an external system for order approvals for more information. |
| Catalog and Price Group Assignment | Integrates systems that determine which catalog and price group a shopper should use to create orders. See Assign Catalogs and Price Groups to Shoppers for more information. |
| Contact Accounts Retrieval | Returns a list of service account IDs for the current user. |
| Services Retrieval | Returns information about a services or assets associated with the current user. |
| Service Actions | Performs a modify, renew, or cancel action on a service or asset. |
| Custom Currency Payment | Integrates custom payment gateways that let your store accept loyalty points payments. |
| Return Request Validation | Validates whether items maintained in an external order management system are eligible for return. |
| Return Request Validation Without Payment Details |
Validates whether items maintained in an external order management system are eligible for return. The body for this webhook does not include payment details. See Understand webhooks and PCI DSS compliance for more information. |
| Order Qualification | Performs order qualification operations prior to submitting the order. |
| Order Validation | Validates the contents of the submitted order after final pricing is performed. |
Validate function webhook responses
As discussed in the previous section, you must ensure the system receiving a function webhook POST responds by sending the appropriate JSON data to Commerce. To determine whether the response data conforms to the correct schema, the ccdebug REST client on the administration server in your test environment includes a validation tool for function webhooks. To access this tool, go to the following URL:
http://<admin-server-hostname>/ccdebugSelect the Function Webhooks tab, and then log into the Admin API. Follow the instructions on the screen to validate the format of your response payloads.