salesforce-webhooks

Salesforce Webhooks (Outbound Messages)

Salesforce has no classic HMAC-signed webhook. The closest native push is the Outbound Message, configured on a Flow or Workflow Rule, which POSTs a SOAP/XML envelope to your HTTPS endpoint when a record changes.

There is no signature header. You authenticate the message by:

1. Validating <OrganizationId> in the SOAP body against your known 18-char Salesforce org id.
2. Enforcing HTTPS and restricting inbound traffic to Salesforce IP ranges.
3. Optionally mutual TLS (Salesforce can present a client certificate).

Your endpoint must return a SOAP <Ack>true</Ack> envelope with HTTP 200, or Salesforce retries the message for up to 24 hours.

When to Use This Skill

• How do I receive Salesforce webhooks / Outbound Messages?
• How do I parse the Salesforce Outbound Message SOAP/XML body?
• How do I validate the OrganizationId on a Salesforce Outbound Message?
• What Ack response does a Salesforce Outbound Message listener return?
• How do I handle Account, Opportunity, Contact, Lead, or Case record changes?
• Should I use Outbound Messages, Platform Events, or Change Data Capture?

Verification (core)

Outbound Messages are unsigned. "Verification" = parse the SOAP body, match <OrganizationId> (timing-safe) against your org id, then return the Ack. Use the raw request body — Salesforce sends Content-Type: text/xml, so parse XML, not JSON.

const { XMLParser } = require('fast-xml-parser');
const crypto = require('crypto');

// removeNSPrefix strips soapenv:/sf: prefixes so we can read plain element names.
const parser = new XMLParser({ ignoreAttributes: false, removeNSPrefix: true });

// rawXml = raw HTTP body string; expectedOrgId = your 18-char Salesforce org id.
function verifyOutboundMessage(rawXml, expectedOrgId) {
  const msg = parser.parse(rawXml)?.Envelope?.Body?.notifications;
  const orgId = String(msg?.OrganizationId ?? '');
  const a = Buffer.from(orgId), b = Buffer.from(expectedOrgId);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    throw new Error('OrganizationId mismatch — reject with 401');
  }
  return msg; // dispatch [].concat(msg.Notification) then return the Ack envelope below
}