​
Webhook Integrations

Yess webhook integrations allow you to receive real-time notifications about engagement events in your external systems. When specific events occur in Yess (such as when an engagement is dispatched or when you receive an inbound response), Yess will send an HTTP POST request to your configured webhook endpoint with detailed information about the event.

​
Overview

Webhooks enable you to:
  • Get notified immediately when engagements are sent
  • Track inbound responses and interactions
  • Sync engagement data with your CRM or other tools
  • Build custom workflows based on Yess events
  • Monitor engagement performance in real-time

​
Setting Up a Webhook

To create a webhook integration, you’ll need to configure:

​
1. Target URL

The HTTP endpoint where Yess will send webhook notifications. This must be:
  • A valid HTTPS URL (HTTP is not supported for security)
  • Publicly accessible from the internet
  • Able to accept POST requests
  • Responsive (should return a 2xx status code within 30 seconds)

​
2. Authentication Headers (Optional)

Custom HTTP headers for authenticating webhook requests, such as:
  • API keys: Authorization: Bearer your-api-key
  • Custom tokens: X-Webhook-Token: your-secret-token
  • Basic authentication: Authorization: Basic base64-encoded-credentials

​
3. Event Types

Select which events should trigger webhook notifications:

​
Available Event Types

Event TypeDescription
engagement_dispatchedTriggered when an outbound engagement (email, LinkedIn message, etc.) is successfully sent
inbound_engagementTriggered when you receive an inbound response (email reply, LinkedIn message, connection request accepted, etc.)
engagement_status_changed (Coming Soon)Triggered whenever the status of an engagement is updated (e.g., from pending to sent, failed to delivered, or replied)

​
Webhook Payload Structure

All webhook payloads follow a consistent structure containing information about the event, account, lead, engagement, and optionally the sequence.

​
Base Payload Structure

{
  "event": "engagement_dispatched",
  "account": {
    // Account information
  },
  "lead": {
    // Lead information
  },
  "engagement": {
    // Engagement details
  },
  "sequence": {
    // Sequence information (if applicable)
  }
}

​
Account Object

{
  "account": {
    "yess_id": "acc_123456789",
    "name": "Acme Corporation",
    "website": "acme.com",
    "linkedin": "https://linkedin.com/company/acme-corp",
    
    // Integration identifiers (when available)
    "salesforce_id": ["001XX000004TMZ2"],
    "hubspot_id": ["12345678"],
    "outreach_id": ["98765"],
    "salesloft_id": ["54321"]
  }
}

​
Lead Object

{
  "lead": {
    "yess_id": "lead_987654321",
    "name": "John Smith",
    "first_name": "John",
    "middle_name": null,
    "last_name": "Smith",
    "linkedin": "https://linkedin.com/in/johnsmith",
    "primary_email": "john.smith@acme.com",
    "other_emails": [
      "j.smith@acme.com",
      "john@acme.com"
    ],
    
    // Integration identifiers (when available)
    "salesforce_lead_id": ["00QXX0000012345"],
    "salesforce_contact_id": ["003XX000004567"],
    "hubspot_id": ["123456"],
    "outreach_id": ["789012"],
    "salesloft_lead_id": ["345678"]
  }
}

​
Engagement Object

The engagement object varies based on the channel and action: 
{
  "engagement": {
    "yess_id": "eng_123abc456def",
    "channel": "email",
    "action": "new_thread_email",
    "subject": "Introduction from Yess",
    "body": "Hi John,\n\nI hope this email finds you well...",
    "operator": {
      "name": "Alice Johnson",
      "email": "alice@yourcompany.com"
    },
    "sponsor": {
      "name": "Bob Wilson", 
      "email": "bob@yourcompany.com"
    }
  }
}

​
Sequence Object (Optional)

Included when the engagement is part of a sequence: 
{
  "sequence": {
    "yess_id": "seq_abc123def456",
    "name": "Cold Outreach - Tech Decision Makers"
  }
}

​
Engagement Channels and Actions

​
Email Channel

Channel: email Actions:
  • new_thread_email - New email thread
  • follow_up_email - Follow-up email in existing thread
  • follow_on_reply_email - Response to an inbound email

​
LinkedIn Channel

Channel: linkedin Actions:
  • linkedin_connect - Connection request
  • linkedin_message - Direct message
  • linkedin_inmail - InMail message
  • linkedin_follow_on_reply - Response to inbound LinkedIn message
  • linkedin_group_chat - Group chat message
  • linkedin_group_chat_follow_up_on_reply - Group chat follow-up

​
Manual Channel

Channel: manual Actions:
  • manual_task - Manual task or action

​
Inbound Actions

For inbound engagements, actions include:
  • reply_email - Email reply received
  • reply_linkedin - LinkedIn message received
  • connection_accepted_linkedin - LinkedIn connection accepted

​
Integration Identifiers

Integration identifiers help you map Yess entities to records in your existing systems:

​
Account Integration Identifiers

  • salesforce_id - Salesforce Account ID
  • hubspot_id - HubSpot Company ID
  • outreach_id - Outreach Account ID
  • salesloft_id - SalesLoft Account ID

​
Lead Integration Identifiers

  • salesforce_lead_id - Salesforce Lead ID
  • salesforce_contact_id - Salesforce Contact ID
  • hubspot_id - HubSpot Contact ID
  • outreach_id - Outreach Prospect ID
  • salesloft_lead_id - SalesLoft Person ID

​
Example Webhook Payloads

​
Email Engagement Dispatched

{
  "event": "engagement_dispatched",
  "account": {
    "yess_id": "acc_7f8e9d1c2b3a",
    "name": "TechCorp Solutions",
    "website": "techcorp.com",
    "linkedin": "https://linkedin.com/company/techcorp-solutions",
    "salesforce_id": ["001XX000004TMZ2"],
    "hubspot_id": ["12345678"]
  },
  "lead": {
    "yess_id": "lead_3a4b5c6d7e8f",
    "name": "Sarah Johnson",
    "first_name": "Sarah",
    "middle_name": null,
    "last_name": "Johnson",
    "linkedin": "https://linkedin.com/in/sarah-johnson-tech",
    "primary_email": "sarah.johnson@techcorp.com",
    "other_emails": [],
    "salesforce_contact_id": ["003XX000004567"],
    "hubspot_id": ["987654321"]
  },
  "engagement": {
    "yess_id": "eng_1a2b3c4d5e6f",
    "channel": "email",
    "action": "new_thread_email",
    "subject": "Quick question about TechCorp's infrastructure needs",
    "body": "Hi Sarah,\n\nI noticed TechCorp has been expanding rapidly...",
	"timestamp": "2025-06-24T13:04:40.553031+00:00",
    "operator": {
      "name": "Mike Chen",
      "email": "mike@yourcompany.com"
    },
    "sponsor": {
      "name": "Lisa Rodriguez",
      "email": "lisa@yourcompany.com"
    },
	"outreach": {
	  "task_id": "2384",
      "sequence_state_id": "43493"
	},
	"salesloft": {
	  "task_id": "68438",
      "cadence_id": "3242223",
      "step_id": "32399",
      "action_id": "2432432"
	}
  },
  "sequence": {
    "yess_id": "seq_abc123def456",
    "name": "Enterprise Outreach Q1 2024"
  }
}

​
Inbound LinkedIn Reply

{
  "event": "inbound_engagement",
  "account": {
    "yess_id": "acc_7f8e9d1c2b3a",
    "name": "TechCorp Solutions", 
    "website": "techcorp.com",
    "linkedin": "https://linkedin.com/company/techcorp-solutions"
  },
  "lead": {
    "yess_id": "lead_3a4b5c6d7e8f",
    "name": "Sarah Johnson",
    "first_name": "Sarah",
    "middle_name": null,
    "last_name": "Johnson",
    "linkedin": "https://linkedin.com/in/sarah-johnson-tech",
    "primary_email": "sarah.johnson@techcorp.com",
    "other_emails": []
  },
  "engagement": {
    "yess_id": "eng_9z8y7x6w5v4u",
    "channel": "linkedin",
    "action": "reply_linkedin",
    "operator": {
      "name": "Mike Chen",
      "email": "mike@yourcompany.com"
    },
    "sponsor": {
      "name": "Lisa Rodriguez", 
      "email": "lisa@yourcompany.com"
    }
  }
}

​
Security Considerations

​
Webhook Verification

To ensure webhooks are coming from Yess:
  • Use HTTPS endpoints only
  • Implement header-based authentication
  • Validate the request structure
  • Consider IP allowlisting to Yess IP -> 52.44.59.155

​
Best Practices

  • Validate payloads: Always validate the structure and content of incoming webhooks
  • Handle failures gracefully: Implement retry logic and error handling
  • Process asynchronously: Handle webhook processing in background jobs to avoid timeouts
  • Secure your endpoint: Use authentication headers and validate requests
  • Monitor and log: Track webhook deliveries and failures for debugging

​
Error Handling

​
Webhook Delivery

Yess will attempt to deliver webhooks with the following behavior:
  • Timeout: 30 seconds per request
  • Retries: Up to 10 attempts with exponential backoff
  • Success criteria: HTTP status codes 200-299
  • Failure handling: After max retries, delivery attempts stop
Your webhook endpoint should:
  • Return appropriate HTTP status codes (200-299 for success)
  • Respond quickly (under 30 seconds)
  • Handle duplicate deliveries gracefully (webhooks may be retried)
  • Log received webhooks for debugging

​
Common HTTP Status Codes

  • 200 OK - Webhook received and processed successfully
  • 400 Bad Request - Invalid payload format
  • 401 Unauthorized - Authentication failed
  • 500 Internal Server Error - Processing error (will trigger retry)

​
Testing Your Webhook

​
Testing Tools

  • Use tools like ngrok to create a public endpoint for local testing
  • Test with webhook testing services like webhook.site
  • Use curl or Postman to simulate webhook payloads

​
Sample Test Payload

You can use this sample payload to test your webhook endpoint: 
{
  "event": "engagement_dispatched",
  "account": {
    "yess_id": "acc_test123",
    "name": "Test Company",
    "website": "test.com",
    "linkedin": "https://linkedin.com/company/test"
  },
  "lead": {
    "yess_id": "lead_test123", 
    "name": "Test User",
    "first_name": "Test",
    "last_name": "User",
    "linkedin": "https://linkedin.com/in/testuser",
    "primary_email": "test@test.com",
    "other_emails": []
  },
  "engagement": {
    "yess_id": "eng_test123",
    "channel": "email",
    "action": "new_thread_email",
    "subject": "Test Subject",
	"timestamp": "2025-06-24T13:04:40.553031+00:00",
    "operator": {
      "name": "Test Operator",
      "email": "operator@test.com"
    },
    "sponsor": {
      "name": "Test Operator",
      "email": "operator@test.com"
    },
	"outreach": {
	  "task_id": "2384",
      "sequence_state_id": "43493"
	},
	"salesloft": {
	  "task_id": "68438",
      "cadence_id": "3242223",
      "step_id": "32399",
      "action_id": "2432432"
	}
  }
}

​
Troubleshooting

​
Common Issues

Webhook not being received:
  • Check that your endpoint is publicly accessible
  • Verify HTTPS is being used
  • Confirm your endpoint returns 2xx status codes
  • Check if authentication headers are configured correctly
Duplicate webhooks:
  • Implement idempotency using the engagement.yess_id
  • Handle retries gracefully in your application
Missing data in payloads:
  • Some fields may be null or missing if data isn’t available
  • Integration identifiers are only included when the entity has been synced from that system
  • The sequence object is only included for sequence-based engagements
Webhook timeouts:
  • Ensure your endpoint responds within 30 seconds
  • Process webhooks asynchronously if heavy processing is needed
  • Return a success status immediately and process in the background
For additional support with webhook integrations, please contact the Yess support team.