Understand webhooks

Oracle Commerce Cloud includes two types of webhooks, event webhooks and function webhooks:

  • Event webhooks are asynchronous; they are triggered by JMS 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 an Oracle Commerce Cloud 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, Oracle Commerce Cloud 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 Oracle Commerce Cloud 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 Oracle Commerce Cloud.

Oracle Commerce Cloud 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.
Order Cancel An agent cancelled an order.
Order Cancel Without Payment Details

An agent cancelled 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.
Remorse Period Start Without Payment Details

An order’s customer remorse period has started.

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 cancelled 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 Oracle Commerce Cloud. 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.

Oracle Commerce Cloud 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.
External Payment Property Metadata Retrieval Integrates custom payment gateways that let Oracle Assisted Selling accept various payment types.
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 Oracle Commerce Cloud. 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>/ccdebug

Select 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.