Webhooks & Event Notifications

Overview

Webhooks allow SalesOS to push real-time notifications to external systems whenever specific events occur in your CRM. Rather than polling the API for changes, webhooks deliver event data to your specified endpoint the moment something happens — a deal moves forward, a contact is created, a payment is received, or any other trackable action.

This event-driven architecture enables powerful automations, keeps connected systems synchronized, and eliminates the latency and overhead of periodic data pulls.

Supported Events

SalesOS supports webhooks for a comprehensive set of CRM events organized by category.

Record Lifecycle Events

Deal & Pipeline Events

Task & Activity Events

Form & Communication Events

Financial Events

Creating a Webhook

Step 1: Navigate to Webhook Settings

Go to Settings > Integrations > Webhooks and click Create Webhook.

Step 2: Configure the Endpoint

Step 3: Add Event Filters

Filters narrow which events trigger the webhook. Without filters, all matching events fire.

• Record type — Only trigger for specific objects (e.g., only Deals, not Leads)
• Field conditions — Only fire when certain field values match (e.g., deal.amount > 10000)
• Owner filter — Only trigger for records owned by specific users or teams
• Pipeline filter — Only trigger for deals in a specific pipeline

Step 4: Save and Activate

Once saved, the webhook begins listening immediately. You can pause it at any time without deleting the configuration.

Payload Format

All webhook payloads are delivered as JSON via HTTP POST. The structure is consistent across all event types.

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "deal.stage_changed",
  "timestamp": "2026-05-25T14:32:08.123Z",
  "version": "2026-01",
  "organization_id": "org_xyz789",
  "data": {
    "record_id": "deal_abc123",
    "record_type": "deal",
    "changes": {
      "stage": {
        "previous": "Proposal Sent",
        "current": "Negotiation"
      }
    },
    "record": {
      "id": "deal_abc123",
      "name": "Acme Corp Enterprise License",
      "amount": 85000,
      "owner_id": "usr_456",
      "stage": "Negotiation",
      "updated_at": "2026-05-25T14:32:08.000Z"
    }
  },
  "metadata": {
    "triggered_by": "usr_456",
    "source": "web_app",
    "ip_address": "203.0.113.42"
  }
}

Payload Fields

Authentication

SalesOS supports multiple methods to verify that incoming webhook payloads are legitimate.

HMAC Signature Verification

Every webhook delivery includes an X-SalesOS-Signature header containing an HMAC-SHA256 hash of the payload body using your webhook secret.

To verify:

1. Retrieve the raw request body (before JSON parsing)
2. Compute HMAC-SHA256 using your webhook secret as the key
3. Compare the computed hash with the value in X-SalesOS-Signature
4. Reject the request if they do not match

The signature header also includes a timestamp component (X-SalesOS-Timestamp) to prevent replay attacks. Reject any payload older than 5 minutes.

Custom Headers

Add up to 5 custom headers that SalesOS includes with every delivery. Useful for API keys or bearer tokens required by your endpoint.

Basic Authentication

Embed credentials directly in the endpoint URL: https://user:[email protected]/webhooks/salesos

SalesOS transmits the credentials via the standard Authorization: Basic header.

Testing Webhooks

Test Delivery

From the webhook detail page, click Send Test Event to deliver a sample payload to your endpoint. The test uses realistic dummy data matching your selected event type.

Payload Inspector

The built-in Payload Inspector shows:

• The exact JSON body that will be sent
• All headers (including authentication headers)
• The computed HMAC signature
• A cURL command to replicate the request manually

Local Development

For local development and testing, SalesOS supports temporary tunnel URLs from services like ngrok or Cloudflare Tunnel. Configure your local tunnel URL as the endpoint during development, then switch to production URLs before going live.

Retry Logic

If your endpoint does not return a 2xx status code, SalesOS retries delivery using exponential backoff.

After 7 failed attempts, the event is marked as permanently failed and no further retries are attempted.

Automatic Disabling

If a webhook endpoint fails to respond successfully for 72 consecutive hours, SalesOS automatically pauses the webhook and sends an email notification to the organization admin. Re-enable it manually once the endpoint issue is resolved.

Webhook Logs

The Delivery History tab on each webhook provides full visibility into every delivery attempt.

Log Entry Details

• Event ID — Unique identifier for the event
• Event Type — The event that triggered delivery
• Timestamp — When the delivery attempt occurred
• Status Code — HTTP response code from your endpoint
• Response Time — How long your endpoint took to respond
• Response Body — First 1KB of the response (for debugging)
• Retry Count — Number of delivery attempts

Filtering Logs

Filter delivery history by:

• Status (Success, Failed, Pending Retry)
• Event type
• Date range
• Response code

Logs are retained for 30 days. Export them as CSV for longer-term analysis.

Managing Webhooks

Pausing and Resuming

Pause a webhook to temporarily stop deliveries without losing configuration. Events that occur while paused are not queued — they are simply not delivered.

Editing

You can modify the endpoint URL, subscribed events, filters, and authentication settings at any time. Changes take effect immediately for subsequent events.

Deleting

Deleting a webhook permanently removes it and all associated delivery logs. This action cannot be undone.

Bulk Operations

From the webhooks list view, select multiple webhooks to:

• Pause or resume in bulk
• Delete multiple webhooks
• Export configurations as JSON (for backup or migration)

Rate Limits

If your endpoint receives events faster than it can process them, implement a queue on your side to buffer incoming payloads.

Common Integrations

Zapier

Use SalesOS webhooks as a trigger in Zapier Zaps:

1. Create a Zap with "Webhooks by Zapier" as the trigger (Catch Hook)
2. Copy the Zapier webhook URL
3. Create a SalesOS webhook pointing to that URL
4. Map the payload fields in your Zap's subsequent steps

Make (formerly Integromat)

Configure a "Custom Webhook" module in Make:

1. Add a Custom Webhook module to your scenario
2. Copy the generated URL
3. Create a SalesOS webhook with that URL
4. Run a test delivery to establish the data structure in Make

Slack Notifications

Send CRM events directly to Slack channels:

1. Create a Slack Incoming Webhook URL for your target channel
2. Create a middleware function (or use Zapier/Make) to transform the SalesOS payload into Slack Block Kit format
3. Route transformed payloads to the Slack webhook URL

Custom Applications

For custom integrations, your endpoint should:

1. Accept POST requests with Content-Type: application/json
2. Validate the HMAC signature before processing
3. Return a 200 status code within 30 seconds
4. Process the event asynchronously if handling takes longer

Security Considerations

Endpoint Security

• Always use HTTPS endpoints — SalesOS rejects plain HTTP URLs
• Validate HMAC signatures on every incoming request
• Implement timestamp validation to prevent replay attacks
• Restrict inbound traffic to SalesOS IP ranges (published in your account settings)

Data Sensitivity

• Webhook payloads may contain sensitive customer data
• Ensure your receiving endpoint has appropriate access controls
• Consider filtering which fields are included in payloads (use field inclusion lists)
• Audit who has access to webhook configuration in your organization

Secret Rotation

Rotate your webhook signing secret periodically:

1. Generate a new secret in webhook settings
2. During the grace period (24 hours), both old and new secrets are valid
3. Update your verification logic to use the new secret
4. After the grace period, only the new secret works

Best Practices

• Use HMAC verification — Always validate webhook signatures to ensure payloads originate from SalesOS and have not been tampered with.
• Respond quickly — Return a 200 response immediately, then process the event asynchronously. Long-running processing should happen in a background job.
• Implement idempotency — Use the event id field to detect and ignore duplicate deliveries. Network issues can cause the same event to be delivered more than once.
• Monitor delivery health — Regularly check webhook logs for elevated failure rates. Set up alerts for repeated failures.
• Use event filters — Subscribe only to the events and record types you need. Overly broad subscriptions waste bandwidth and processing resources.
• Handle schema evolution — Parse payloads tolerantly. New fields may be added to payloads without a version change. Never fail on unknown fields.
• Keep endpoints available — Ensure your webhook endpoint has high uptime. Use redundant infrastructure or a message queue as a buffer.
• Log incoming payloads — Store raw payloads before processing them. This aids debugging when integration issues arise.
• Test before going live — Use the test delivery feature and payload inspector to validate your endpoint handles the format correctly before activating in production.
• Document your webhooks — Maintain a registry of active webhooks, their purposes, and the team responsible for each receiving endpoint.