# Salesforce Trigger Webhook

Handles instant enrichment on Salesforce record creation/updates via webhook.

## Overview
The Salesforce Trigger API provides instant enrichment capabilities for Salesforce records through
webhook-based triggers. It supports both real-time webhook processing and polling-based enrichment
for comprehensive coverage of record changes.

## Request Body
- object: Salesforce object type that triggered the event (Lead, Contact, Account, Opportunity)
- ids: List of Salesforce record IDs that changed
- event: Salesforce trigger event type (after_insert, after_update, after_undelete)
- org_id: Salesforce organization ID

## Trigger Events
- after_insert: Triggered when new records are created
- after_update: Triggered when existing records are updated
- after_undelete: Triggered when records are undeleted

## Response Fields
- success: Boolean indicating request success
- processed_count: Number of records processed
- enrichment_jobs: List of enrichment job IDs created
- workflow_status: Status of the enrichment workflow (started, queued, failed)
- credits_consumed: Number of credits used
- credits_remaining: Credits remaining in account
- processing_time_ms: Processing time in milliseconds
- cached: Whether result was from cache

## Enrichment Options

### Webhook Processing (Real-time)
- Immediate Processing: Records are processed immediately upon webhook receipt
- Platform Events: Uses Salesforce Platform Events for reliable delivery
- Apex Callouts: Triggered via Apex callouts from Salesforce triggers
- Low Latency: Near real-time enrichment with minimal delay

### Polling Processing (Fallback)
- SOQL Queries: Polls Salesforce every 2 minutes for new/changed records
- Watermark Tracking: Uses SystemModstamp and Id for efficient filtering
- Batch Processing: Processes records in batches for optimal performance
- Reliable Coverage: Ensures no records are missed even if webhooks fail

## Features
- Dual Processing: Both webhook and polling support for comprehensive coverage
- Automatic Enrichment: Triggers enrichment workflows based on object type
- Job Tracking: Creates enrichment jobs for monitoring and debugging
- Credit Management: Tracks credit consumption per enrichment job
- Error Handling: Robust error handling with retry mechanisms
- Audit Trail: Comprehensive logging for compliance and debugging

## Credit Usage
Trigger processing consumes credits based on enrichment type:
- Lead Enrichment: 2 credits per lead
- Contact Enrichment: 1 credit per contact
- Account Enrichment: 3 credits per account
- Opportunity Enrichment: 1 credit per opportunity

Endpoint: POST /v1/triggers/salesforce
Version: 1.4.1
Security: BearerAuth

## Request fields (application/json):

  - `object` (string, required)
    Salesforce object type that triggered the event
    Enum: "lead", "contact", "account", "opportunity"

  - `ids` (array, required)
    List of Salesforce record IDs that changed

  - `event` (string, required)
    Salesforce trigger event type
    Enum: "after_insert", "after_update", "after_undelete"

  - `org_id` (string, required)
    Salesforce organization ID

## Response 200 fields (application/json):

  - `success` (boolean, required)
    Boolean indicating request success

  - `processed_count` (integer, required)
    Number of records processed

  - `enrichment_jobs` (array, required)
    List of enrichment job IDs created

  - `workflow_status` (string, required)
    Status of the enrichment workflow
    Enum: "started", "queued", "failed"

  - `credits_consumed` (integer, required)
    Number of credits used for this request

  - `credits_remaining` (integer, required)
    Credits remaining in your account after this request

  - `processing_time_ms` (integer, required)
    Time taken to process the request in milliseconds

  - `cached` (boolean, required)
    Boolean indicating if this result was returned from cache

## Response 400 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 401 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 402 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 422 fields (application/json):

  - `detail` (array)

  - `detail.loc` (array, required)

  - `detail.msg` (string, required)

  - `detail.type` (string, required)

## Response 429 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 500 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors