Logging to Google Chat

Google Chat Notifications for Log Events

RFLIB can post a notification to a Google Chat space whenever a log event is published at or above a configured severity threshold. The integration uses a Google Chat Incoming Webhook and Salesforce Named Credentials to keep the webhook URL secure.

---

Prerequisites

• A Google Workspace account. Incoming Webhooks are a Google Workspace feature and are not available for personal Google (Gmail) accounts.
• A Google Chat space where you have permission to manage apps and webhooks
• Salesforce org with RFLIB v11.0.0 or later deployed
• Permission to manage Named Credentials in Salesforce Setup

---

Step 1 — Create a Google Chat Incoming Webhook

1. In Google Chat, open (or create) the space where notifications should appear.
2. Click the space name at the top to open the space menu and choose Apps & integrations.
3. Under Webhooks, click Add webhooks (or Manage webhooks if one already exists).
4. Give the webhook a name (e.g. RFLIB Logger), optionally provide an avatar URL, and click Save.
5. Google Chat generates a webhook URL. Copy it — this is your webhook URL.

   https://chat.googleapis.com/v1/spaces/AAAA.../messages?key=...&token=...
   

   Keep this URL private. The key and token query parameters act as a bearer token — anyone with the URL can post to your space.

---

Step 2 — Store the Webhook in a Named Credential

The webhook URL must be stored as a Named Credential so it is never visible in code, Custom Settings, or SOQL queries. In the modern Salesforce model a Named Credential references an External Credential, so this step has three parts: create the External Credential, add a Principal, then create the Named Credential.

2a — Create the External Credential

1. In Salesforce Setup, search for Named Credentials and open it.

2. Select the External Credentials tab and click New.

3. Fill in the fields:

   Field	Value
   Label	Google Chat
   Name	Google_Chat
   Authentication Protocol	No Authentication

   The Google Chat webhook URL embeds its own key and token, so no additional authentication protocol is required.

4. Click Save.

2b — Add a Principal

1. On the Google Chat External Credential detail page, scroll to the Principals section and click New.
2. Set the Parameter Name to RFLIB Google Chat and leave the Sequence Number as 1.
3. Click Save. The Principal's Authentication Status should show Configured.

The running user (or the Automated Process user, depending on how the RFLIB Log Event Handler flow runs) must be granted access to the Google Chat External Credential through a Permission Set. Without this access, callouts fail with an authorization error.

2c — Create the Named Credential

1. Back on the Named Credentials tab, click New.

2. Fill in the fields:

   Field	Value
   Label	RFLIB Google Chat Integration
   Name	RFLIB_GOOGLE_CHAT_WEBHOOK (must match exactly)
   URL	Paste the Google Chat webhook URL from Step 1
   Enabled for Callouts	Checked
   External Credential	Google Chat

3. Click Save.

Sandbox vs Production: Named Credentials are org-specific. You must create this credential separately in each sandbox and in production. Using different webhook URLs per environment lets you route sandbox notifications to a dedicated Google Chat space.

---

Step 3 — Configure the Log Level Threshold

1. In Salesforce Setup, search for Custom Settings and open rflib_Logger_Settings__c (Logger Settings).

2. Click Manage, then either edit the existing org default or click New to create one.

3. Set the Google Chat Log Level field to the minimum severity that should trigger a notification:

   Value	Behaviour
   NONE	Disabled — no Google Chat notifications sent (default)
   FATAL	Only FATAL events
   ERROR	ERROR and FATAL events
   WARN	WARN, ERROR, and FATAL events
   INFO and below	Not supported (clamps to WARN at runtime)

   Most teams start with ERROR or WARN.

4. Click Save.

The Google Chat Log Level setting is a Hierarchy Custom Setting, meaning it can be overridden at the Profile or User level if finer-grained control is needed. WARN is the enforced minimum — INFO, DEBUG, and TRACE events are never sent to Google Chat regardless of this setting.

---

How It Works

When a rflib_Log_Event__e Platform Event is published, the RFLIB Log Event Handler flow fires. If the event's level meets the configured Google Chat Log Level threshold, rflib_SendLogEventGoogleChatAction posts a cardsV2 card message to the configured Google Chat space.

The message is a single card containing:

• Header — RFLIB Log Event – <Log Level> with the Org Name as the subtitle
• Log Level — the severity of the event
• Created By — the Salesforce User ID that triggered the event
• Context — the logger context string
• Request ID — the transaction request ID for correlation
• Log Messages — the log output (truncated from the beginning at 2,800 characters so the exception at the tail is visible)
• Platform Info — governor limit snapshot in formatted JSON (truncated at 2,800 characters)

HTML escaping: Google Chat renders card text as limited HTML, so RFLIB escapes the HTML-significant characters (&, <, >) in the log content. This ensures angle-bracket text such as XML/HTML snippets, generic type names, or <init> stack frames is delivered verbatim rather than being interpreted as markup.

Execution order in the flow:

Platform Event fires
       │
       ▼
Log to HTTP Endpoint  (rflib_HttpCalloutLogAction)
       │  ← fault skips to next step
       ▼
Send Log Event to Slack  (rflib_SendLogEventSlackAction)
       │  ← fault skips to next step
       ▼
Send Log Event to Teams  (rflib_SendLogEventTeamsAction)  ← runs in a new transaction
       │  ← fault skips to next step
       ▼
Send Log Event to Google Chat  (rflib_SendLogEventGoogleChatAction)  ← runs in a new transaction
       │  ← fault skips to next step
       ▼
Archive Log Event  (rflib_ArchiveLogAction)
       │  ← fault skips to next step
       ▼
Send Log Event Emails  (rflib_SendLogEventEmailAction)

Each step has a fault connector that continues to the next action, so a Google Chat failure never prevents archiving or email from running. The Google Chat step runs in a new transaction to isolate its governor limits from the preceding callout actions.

Notification cap: To protect against floods, RFLIB sends at most 20 Google Chat notifications per flow invocation by default. Override this with the Max_GChat_Notifications_Per_Invocation Global Setting (rflib_Global_Setting__mdt). Events beyond the cap are skipped for that invocation.

---

Troubleshooting

No messages appearing in Google Chat

• Verify the Named Credential name is exactly RFLIB_GOOGLE_CHAT_WEBHOOK (case-sensitive).
• Confirm Google Chat Log Level in Logger Settings is not NONE and matches the severity of the events you are generating (remember the WARN floor).
• Check the rflib_Application_Event__c object for records with Event_Name__c = 'rflib-google-chat-log-event-failed' — these capture failure details including HTTP status codes and exception messages.
• Confirm the webhook still exists in the space's Apps & integrations → Webhooks list; deleting the space or webhook invalidates the URL.

CalloutException: Unauthorized endpoint error in Application Events

The webhook URL in the Named Credential may be incorrect, or the webhook may have been deleted. Recreate the webhook in the Google Chat space and update the Named Credential URL.

Messages are truncated

Google Chat caps card payloads at roughly 32 KB. RFLIB caps each text block at 2,800 characters. Log messages are truncated from the beginning (not the end) so the exception at the tail is always visible, prefixing the block with [TRUNCATED]. Platform info is also truncated at 2,800 characters. This is expected behaviour for very verbose log events. Consider raising the General Log Level setting to reduce noise captured in events.

Notifications firing too frequently

Raise the Google Chat Log Level threshold (e.g., from WARN to ERROR). You can also set a user- or profile-level override in Logger Settings to suppress Google Chat notifications for high-volume automated processes, or lower the Max_GChat_Notifications_Per_Invocation Global Setting.

---

Security Considerations

• The webhook URL is a secret. Store it only in the Named Credential — never in Custom Settings, Apex code, or Custom Metadata.
• Restrict edit access to the Named Credential to System Administrators only.
• Log messages processed by RFLIB are subject to masking rules (rflib_Masking_Rule__mdt) before the Platform Event is published, so sensitive data masked at the logger level will not appear in Google Chat.
• Rotate the webhook URL periodically (recreate the webhook in the space) and update the Named Credential accordingly.