Using External Hooks

External Hooks in SAP Sales Cloud and SAP Service Cloud Version 2 are webhook-based extension points that allow you to integrate custom logic and external services into business processes. By leveraging external hooks, you can trigger external services or functions at specific points— for example setting default values for the standard and custom fields —without modifying standard application code. These external hooks work seamlessly with the SAP Sales Cloud and SAP Service Cloud Version 2 extensibility framework, complementing determinations and validations.

To enable integration with external services, you must first set up a Communication System, which enables secure data exchange between SAP Sales Cloud and SAP Service Cloud Version 2 and external systems. This defines how SAP Sales Cloud and SAP Service Cloud Version 2 connect with external applications, such as microservices on SAP Business Technology Platform (BTP).

You can set up a Communication System to define the connection details and authentication information for your external services. This includes specifying the protocol, target hostname, and authentication method.

Two types of Communication Systems are supported:

• Outbound Communication Systems are used to send data from SAP Sales Cloud and SAP Service Cloud Version 2 to external services, enabling your external custom logic to be triggered by business events (for example, when a Case is created).

• Inbound Communication Systems are used when external services need to create/update data into or read/delete data from SAP Sales Cloud and SAP Service Cloud Version 2.

By configuring Communication Systems, you establish secure, reliable connections that support seamless data exchange and extensibility across your SAP Sales Cloud and SAP Service Cloud Version 2.

For detailed configuration steps, please refer to Create a Communication System.

Think of an External Hook as a checkpoint in the entity save process. When a user creates or updates a record, such as a Case, an Opportunity, or an Account, the system can pause and make a call to an external web service that you have built. This callout allows your custom code to inspect the data, modify it, or even stop the save process if your business rules are not met. It is the primary method for implementing side-by-side extensions that require synchronous, or real-time, interaction with the system during a transaction.

It's critical to understand the two main extension patterns, as your choice directly impacts system performance and the user's experience.

External Hooks are synchronous; they execute during the entity save transaction, which means the user must wait for your external code to finish before the system can continue. Only one Pre Hook and Post Hook can be created per each root entity, like Case, Lead, and Account. They are not allowed for sub-entities because they block the process, and performance becomes a key consideration.

• Pre Hook: Executes before the system's standard validations. This is your chance to prepare the data before SAP's standard logic runs.

  • Use Case: Defaulting or modifying values in both standard and custom fields.

  • Real-World Scenario: A sales representative creates a new Opportunity. A Pre Hook calls an external pricing engine to calculate a complex preliminary discount based on the customer's history and proposed products, then automatically populates the "Discount" and "ApprovalReason" fields.

• Post Hook: Executes after the system's standard validations have passed but before the data is committed to the database.

  • Use Case: Running final validations and updating custom (extension) fields only.

  • Real-World Scenario: When a service agent tries to close a high-priority Case, a Post Hook validates that a custom field "RootCauseAnalysis" has been filled out. If it's empty, the hook returns an error message to the user, and the save fails, ensuring process compliance.

Implementing an external hook involves two main parts: configuration within SAP Sales Cloud and SAP Service Cloud Version 2, and the development of your external service.

First, you need to perform the configuration inside SAP Sales Cloud and SAP Service Cloud Version 2. This involves creating a Communication System to define the target URL and authentication for your external service. Then, navigate to System Settings→Extensibility Administration, select your business entity (such as a Lead), and create a new External Hook. In this step, you can choose the Event (Pre Hook or Post Hook), API Path, HTTP Method, and link it to your Communication System.

After performing the configuration, you need to develop your external service. This external service must expose an HTTP POST endpoint that SAP Sales Cloud and SAP Service Cloud Version 2 can call. Your external service will need to process the incoming request and send back a correctly formatted response.

• The Request Payload: Your external service will receive a JSON payload containing:
  • entity: The name of the business entity.
  • beforeImage: The state of the entity before the user's changes.
  • currentImage: The state of the entity after the user's changes.
  • context: Information about the user, language, and the operation (Create, Update).
• The Response Payload: Your external service has to return a JSON payload.
  • To modify data, you return the entire currentImage entity with your changes.
  • To trigger a validation error, you return a structured error message.
  • If no changes are made, you can simply return {"noChanges": true} for better performance.

For more details on the request and response payload structures, please refer to External Hook Request and Response Structure on the SAP Help portal.

In SAP Sales Cloud and SAP Service Cloud Version 2, custom logic and its execution (including external hooks) are traceable and loggable, enabling administrators and developers to diagnose runtime system behavior.

When integrating external hooks into SAP Sales Cloud and SAP Service Cloud Version 2, it’s essential to recognize why these integrations might fail. Here are the most common reasons external hooks fail, helping you proactively address and resolve these challenges in your projects.

• Connectivity and authentication issues: invalid destination, expired credentials, or blocked network route produce HTTP error status or timeouts in logs.

• Payload/schema mismatch: the external service rejects the request due to missing or unexpected fields; logs show 4xx responses and error messages from the target.

• External Hook timing and business entity lifecycle: if the external hook is bound to an event (for example, after save) but prerequisites (like required fields or status) are not met, the external hook may not trigger; logs show no execution or show a skipped condition.

• Authorization and scoping: the technical user or registered destination lacks permission to call the target or to read/write the involved entity; logs show authorization failures.

To troubleshoot external hooks with application logs, navigate to the Logs tab on the Extensibility Administration screen of a business entity like Lead. You can identify the log entries by User, Timestamp, or Actions.

You can choose the View Details action button on a log entry and inspect common log fields like Process Name, Timestamp, Log Level, Service Name, and Description.

• External Hooks are webhook-based extension points in SAP Sales Cloud and SAP Service Cloud Version 2 that allow you to inject custom business logic or perform validations and determinations by integrating with external services during save operations—without altering standard application code.
• Communication Systems must be configured to establish secure, authenticated connections between SAP Sales Cloud and SAP Service Cloud Version 2 and external services; outbound systems call external services, while inbound systems receive calls from external services.
• Pre Hooks execute before standard validations, enabling you to modify or default data before SAP logic runs (for example, calculating and populating discounts via an external service).
• Post Hooks execute after standard validations but before database commit, allowing final validations or custom field updates (for example, enforcing required fields before saving).
• External Hook Setup involves configuring both the Communication System and the External Hook (including event type, API path, HTTP method, and linking to the Communication System), plus developing an external service to handle JSON request and response payloads as specified.
• Troubleshooting is supported through application logs, which help diagnose issues such as connectivity, authentication, payload mismatches, event timing, and authorization problems by providing detailed log entries and error descriptions in the Extensibility Administration area.