> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-presentations/integration-logs.md).

# Integration Payloads

Understand integration payload presentations including request/response visualizers, HTTP interaction details, and Apex callout context.

Integration payloads in Pharos provide specialized presentations for external system interactions, combining HTTP request/response details with the surrounding Apex execution context to create complete visibility into how Salesforce communicates with external APIs and services.

An integration payload is a `{request, response}` pair attached to a log—typically an **Apex-category** log produced via Triton's `integrationPayload` methods. The presentation features on this page are payload-driven: they activate on any log carrying such a payload, whatever its category.

{% hint style="info" %}
**Complete Integration Visibility:** See both sides of the integration—what Salesforce sent and what it received—with HTTP details connected to the Apex code that initiated the callout.
{% endhint %}

{% hint style="warning" %}
**The Integration log Category is removed.** New callout/REST logs are Apex-category logs carrying an integration payload—the Triton builder defaults to Apex, and `TritonTypes.Category.Integration` has been removed. To migrate custom Apex, drop the `.category()` call and keep `.integrationPayload()`. The `Integration` picklist value is removed from the picklist, but historical records keep it, and legacy producers that still send it keep working.
{% endhint %}

## The Integration Debugging Challenge

When Salesforce integrates with external systems through HTTP callouts, failures can originate from multiple sources:

* **Apex logic errors** — Incorrect request construction, parameter marshaling, or response parsing
* **External system errors** — The API returned an error status, malformed response, or unexpected data structure
* **Network issues** — Timeouts, connection failures, or DNS resolution problems
* **Authentication failures** — Invalid credentials, expired tokens, or missing headers
* **Data mapping problems** — Field mismatches between Salesforce and external system data models

Debugging these failures requires visibility into both sides of the integration: what Salesforce sent and what it received. Standard Salesforce debug logs contain this information, but it's often fragmented across different log sections or truncated due to size limits. Integration-specific Apex code appears alongside unrelated system events, making it difficult to isolate the callout interaction.

Pharos addresses this by recognizing logs that carry integration payloads and presenting them with specialized views that highlight HTTP interactions and connect them to the Apex code that initiated them.

## How Pharos Recognizes Integration Payloads

Recognition is by payload shape, not category. When a log carries a `{request, response}` payload—set via Triton's `integrationPayload` methods, or attached by Pharos's own capture of callout failures—post-processing preserves it and the presentation features on this page activate. This works for **any** log category: the request/response viewer has always keyed off the payload itself, and payload preservation now follows the same rule everywhere.

Once a log is recognized as carrying an integration payload, additional presentation features activate to surface HTTP-specific details.

## Request/Response Visualizer

The core feature of integration payload presentation is the **Request/Response Visualizer**, which formats HTTP interactions for readability and analysis.

### HTTP Request Details

The request panel displays everything Salesforce sent to the external system:

**Request Line:**

* HTTP Method (GET, POST, PUT, DELETE, PATCH)
* Target URL including query parameters
* HTTP Version

**Request Headers:** Presented as a formatted table rather than raw text, with special highlighting for authentication-related headers:

* `Authorization` (with sensitive tokens partially masked for security)
* `Content-Type`
* `Accept`
* Custom headers required by the API

Headers are searchable and sortable, making it easy to verify that required headers were included with correct values.

**Request Body:** For POST and PUT requests, the request body is formatted based on content type:

* **JSON** — Syntax-highlighted and pretty-printed with collapsible sections for nested objects
* **XML** — Formatted with proper indentation and syntax highlighting
* **Form Data** — Presented as key-value pairs
* **Plain Text** — Displayed as-is
* **Binary** — Indicated with content type and size (not displayed)

Large request bodies can be expanded or collapsed, and specific sections can be copied for testing in external tools like Postman.

**Request Size and Timing:**

* Total request size in bytes
* Time when request was initiated (precise timestamp)

This complete view of the request enables verification that Salesforce is sending what the external API expects.

### HTTP Response Details

The response panel shows everything the external system returned to Salesforce:

**Status Line:**

* HTTP Status Code (200, 400, 500, etc.)
* Status Message ("OK", "Bad Request", "Internal Server Error")
* Status code significance (success, client error, server error) is color-coded

**Response Headers:** Similar table format as request headers, highlighting important information:

* `Content-Type` (indicates how to parse the response body)
* `Content-Length`
* Rate limiting headers (`X-RateLimit-Remaining`, etc.)
* Caching headers
* Custom headers from the API

**Response Body:** Formatted based on the `Content-Type` header:

* **JSON** — Syntax-highlighted and collapsible, making it easy to navigate complex response structures
* **XML** — Properly indented with syntax highlighting
* **HTML** — Rendered or shown as formatted source (useful for API error pages)
* **Plain Text** — Error messages or simple responses
* **Binary** — Indicated but not displayed

Error responses are especially important. When an API returns a 4xx or 5xx status code, the response body typically contains error details explaining why the request was rejected. The visualizer highlights these error responses and extracts key error information:

* Error codes from the API
* Error messages
* Validation failure details
* Debugging information provided by the external system

**Response Size and Timing:**

* Total response size in bytes
* Time when response was received
* **Response Duration** — How long the external system took to respond (calculated as receive time minus send time)

This timing information is critical for identifying whether integration slowness stems from network latency, external system processing time, or Salesforce processing time.

### Side-by-Side Comparison

The Request/Response Visualizer can display request and response side-by-side, enabling quick comparison:

* Verify that request parameters map to response data
* Trace how input values were transformed or validated
* Identify which request fields caused validation errors in the response

This is particularly useful for REST APIs where the response structure mirrors the request structure.

## Apex Callout Context

Logs with integration payloads don't just show the HTTP interaction—they also show the **Apex execution context** that surrounded the callout.

### Calling Code Location

The log identifies:

* Which Apex class made the HTTP callout
* Which method performed the request
* The line number where `Http.send()` or similar was called

This connects the HTTP details back to the code responsible, enabling navigation to the source code for fixes.

### Request Construction Logic

The Apex debug output before the callout is analyzed to show:

* How the request URL was constructed (from string concatenation, variables, or configuration)
* How headers were set
* How the request body was built (especially for JSON/XML serialization)
* Any parameters or variables used in request construction

If the request is malformed, this context reveals where in the Apex logic the problem was introduced.

### Response Processing Logic

The Apex debug output after the callout is analyzed to show:

* How the response was parsed (JSON deserialization, XML parsing)
* Which response fields were extracted
* Any validation or error handling logic that executed
* Exceptions thrown during response processing

If the integration fails because Salesforce can't parse the response, this context pinpoints the parsing code that needs adjustment.

### Stack Trace for Callout Exceptions

When a callout throws an exception (timeout, connection failure, SSL error), the full Apex stack trace is included:

* The exact point where the exception was thrown
* The calling methods up the stack
* Whether the exception was caught and handled or propagated

This makes it clear whether error handling logic is working as intended or needs improvement.

## Authentication and Security Context

Integrations often involve authentication mechanisms. The integration payload presentation highlights authentication-related aspects:

### Named Credentials

If the callout used Named Credentials (Salesforce's secure credential storage):

* Named Credential name is displayed
* Authentication protocol (OAuth 2.0, JWT, Basic Auth, etc.)
* Indication of whether authentication succeeded or failed

Sensitive credential values are never logged, but authentication metadata helps verify configuration correctness.

### OAuth Tokens

For OAuth-based integrations:

* Token type (Bearer, etc.)
* Token partially displayed (first/last few characters only)
* Token expiration status (if available)
* Refresh token usage (whether token was refreshed during the callout)

This helps diagnose authentication failures due to expired or invalid tokens.

### Certificate and SSL Issues

If the callout failed due to SSL/TLS problems:

* Certificate validation errors
* Hostname verification failures
* Protocol version mismatches

These errors are highlighted with guidance on resolution (e.g., "Add remote site certificate to Salesforce trusted certificates").

## Common Integration Failure Patterns

The integration payload presentation specifically highlights common failure scenarios:

### Timeout Errors

When a callout exceeds Salesforce's timeout limit (120 seconds for synchronous, configurable for async):

* The timeout threshold is displayed
* How long the callout waited before timing out
* Suggested actions (increase timeout if possible, optimize external API, use async pattern)

### Connection Failures

When Salesforce can't establish a connection to the external system:

* The target URL that couldn't be reached
* Network error details (DNS resolution failure, connection refused, etc.)
* Whether the remote site is configured in Salesforce settings

### 4xx Client Errors

When the external API rejects the request due to client errors (400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found):

* The specific 4xx status code
* Error details from the response body
* Which request elements likely caused the rejection (missing parameters, invalid authentication, incorrect URL)

These are typically issues with how Salesforce constructed or authenticated the request.

### 5xx Server Errors

When the external API experiences internal errors (500 Internal Server Error, 503 Service Unavailable):

* The specific 5xx status code
* Any error details the server provided
* Indication that the issue is on the external system side, not Salesforce

This distinction helps determine whether to fix Salesforce code or contact the external API vendor.

### Response Parsing Failures

When Salesforce successfully receives a response but can't parse it:

* The expected format (JSON, XML) vs. what was received
* Parsing error details (unexpected structure, missing fields, type mismatches)
* The portion of the response that caused the parsing failure

This indicates a mismatch between what the Apex code expects and what the API actually returns—often due to API version changes or inadequate error handling.

## Performance Analysis for Integrations

Logs with integration payloads include performance metrics specific to external callout scenarios:

### Latency Breakdown

The log breaks down where time was spent:

* **Apex Preparation Time** — Time spent in Apex code before making the callout (constructing request, gathering data)
* **Network/External Processing Time** — Duration of the HTTP callout itself (time from send to receive)
* **Apex Processing Time** — Time spent in Apex code after receiving the response (parsing, storing data, triggering subsequent logic)

This breakdown identifies whether slowness is due to Salesforce code or the external system.

### Callout Count and Governor Limits

Salesforce enforces limits on callouts:

* Maximum callout duration in a transaction (120 seconds synchronous)
* Maximum number of callouts (100 per transaction)

The log displays:

* How many callouts were made in the transaction
* How much of the callout time budget was consumed
* Whether the transaction is approaching or exceeded limits

Multiple callouts in a single transaction are highlighted, as this often indicates an optimization opportunity (batching requests, using async patterns).

### Callout Retry Logic

If the Apex code includes retry logic for failed callouts, the log traces:

* How many retry attempts were made
* Wait time between retries
* Which attempt ultimately succeeded (or all failed)

This helps evaluate whether retry strategies are working effectively or causing unnecessary delays.

## Integration with Issue Tracking

Integration failures group into Issues through Pharos's standard stacktrace-driven fingerprinting, the same as any other Apex error: the fingerprint is computed from the parsed stack trace lines plus the error summary, with dynamic values (GUIDs, record Ids, digits) stripped for stability. The integration payload itself is not a fingerprint input—it travels with each log as debugging context.

An Issue therefore represents a recurring failure point in the calling code:

"CalloutException in InventoryService.checkStock: 503 Service Unavailable from the Inventory API"

From the Issue detail page, you can see:

* How often this callout site fails
* Whether failures correlate with specific times (indicating external system downtime windows)
* Which Salesforce users or processes trigger the callout most frequently

This pattern analysis helps distinguish between transient external system issues (occasional 503s) and systemic integration problems (consistent 401 authentication failures).

These Issues live alongside other Apex Issues. During the transition off the removed Integration category, a legacy producer still logging the Integration category and an upgraded producer logging the same error as Apex produce the same fingerprint but form separate Issues—different categories never share an Issue—converging into one once the legacy producer is upgraded.

## Bulk Callout Scenarios

Some integration patterns involve making multiple callouts in batch scenarios (e.g., calling an API once per account in a list). The integration payload presentation handles this by:

* Grouping related callouts within the same transaction
* Showing aggregate success/failure rates (50 callouts: 45 succeeded, 5 failed)
* Highlighting which specific callouts failed and why
* Performance summary (average response time across callouts)

This aggregation prevents overwhelming detail while still providing drill-down to individual callout failures.

## Mock and Test Callouts

When integration code runs in test contexts with mock callouts (using `HttpCalloutMock`), the log indicates:

* That the callout was mocked (not a real external call)
* Which mock class provided the response
* The mock response that was returned

This helps verify that test mocks accurately simulate production callout behavior.

## Asynchronous Integration Patterns

Integrations often use asynchronous patterns (Queueable, Future methods, Platform Events) to avoid governor limits. Logs for async callouts include:

* The async job ID
* What code enqueued the async operation
* How long after enqueue the callout executed
* Correlation back to the originating transaction (if using Triton transaction logging)

This traces async integration workflows end-to-end, even though they span multiple Salesforce transactions.

## Exporting Integration Details

For integration debugging with external API vendors, you can export:

* Full request/response details as cURL commands for reproduction
* Request/response bodies as JSON or XML files
* HTTP headers as text files

This enables sharing exact callout details with API support teams without exposing the entire Salesforce debug log.

## Summary

Integration payload presentations in Pharos provide comprehensive visibility into external system interactions by combining HTTP request/response details with the surrounding Apex execution context—on any log carrying a request/response payload.

**Key Features:**

* **Request/Response Visualizer:** Formatted HTTP interactions with syntax-highlighted JSON/XML, collapsible sections, searchable headers
* **Complete HTTP Details:** Request line, headers (with auth masking), body formatting, response status/headers/body
* **Timing & Performance:** Request duration, timeout detection, latency measurements
* **Error Analysis:** Status code interpretation, response error parsing, authentication failure detection
* **Apex Context:** Stack trace connecting to callout code, surrounding execution details
* **Pattern Recognition:** Recurring endpoint failures, authentication issues, timeout patterns
* **Export Options:** Request/response as JSON/XML files, headers as text files

**The Result:** By presenting both what Salesforce sent and what it received—along with timing, performance, and error information—integration payloads enable rapid troubleshooting of API failures, authentication issues, and data mapping problems. Whether debugging a single failed callout or analyzing patterns across thousands of integration attempts, payload-driven presentations ensure that the right information is surfaced for effective resolution.
