Webhooks allow SalesSheet.ai to send real-time notifications to your external systems whenever specific events occur in your CRM. Instead of repeatedly polling the API to check for changes, webhooks push data to your server the moment something happens - a new contact is created, a deal changes stage, or a task is completed.
This push-based approach is more efficient than polling, uses fewer API resources, and delivers data with near-zero latency. Webhooks are essential for building real-time integrations, keeping external databases in sync, and triggering time-sensitive automated workflows.
Antes de Comecar
- An active SalesSheet.ai account on a Pro or Enterprise plan
- Organization admin permissions in SalesSheet.ai to configure webhooks
- A publicly accessible HTTPS endpoint on your server to receive webhook payloads
- Basic understanding of HTTP POST requests, JSON payloads, and server-side request handling
Navigate to Webhook Settings
From your SalesSheet.ai dashboard, go to Settings > Integracoes > Webhooks. This page displays all your configured webhook endpoints along with their status, event subscriptions, and recent delivery history. If you have not set up any webhooks yet, you will see an empty state with a "Create Webhook" button.
Click "Create Webhook" to open the configuration panel. You can create up to 10 webhook endpoints on a Pro plan and up to 50 on an Enterprise plan. Each endpoint can subscribe to different combinations of events, allowing you to route specific data to different systems.
Create Your Endpoint
In the configuration panel, enter a descriptive name for your webhook (for example, "Data Warehouse Sync" or "Marketing Automation Trigger"). Then enter the full URL of your receiving endpoint. This must be a publicly accessible HTTPS URL - SalesSheet.ai does not deliver webhooks to HTTP endpoints or private IP addresses for security reasons.
Optionally, set a signing secret to verify that incoming webhook payloads genuinely originate from SalesSheet.ai. When a secret is configured, each webhook delivery includes an X-SalesSheet-Signature header containing an HMAC-SHA256 hash of the request body. Your server should compute the same hash using the shared secret and compare it to the header value to validate authenticity.
You can also configure custom HTTP headers that SalesSheet.ai will include with every webhook delivery. This is useful for passing authentication tokens or API keys required by your receiving server.
Select Events to Subscribe To
Choose which CRM events should trigger webhook deliveries to this endpoint. Available events are organized by resource type. Contato events include contact.created, contact.updated, and contact.deleted. Deal events include deal.created, deal.updated, deal.stage_changed, deal.won, and deal.lost.
Additional events include task.created, task.completed, activity.created (covering emails, calls, and meetings), and pipeline.updated. You can subscribe to individual events or use the "Select All" option to receive notifications for every event type. We recommend subscribing only to the events you need to minimize unnecessary traffic to your server.
Each webhook payload includes the event type, a timestamp, the full resource object that triggered the event, and a unique delivery ID for deduplication. For update events, the payload also includes a changes object showing which fields were modified and their previous values.
Test Your Webhook
Before activating your webhook, use the "Send Test Event" button to verify your endpoint is working correctly. Select an event type from the dropdown and click "Send." SalesSheet.ai will send a sample payload to your endpoint containing realistic test data with a special "test": true flag so your system can distinguish test deliveries from real ones.
Your endpoint must respond with an HTTP 2xx status code (200, 201, or 204) within 10 seconds to confirm receipt. If your endpoint returns a non-2xx status code or times out, the test will show as failed with the response details. Review your server logs to diagnose any issues before proceeding to activate the webhook.
Monitor Deliveries and Retry Logic
After activating your webhook, you can monitor delivery history from the webhook detail page. Each delivery shows the event type, timestamp, HTTP response code from your server, response time, and whether the delivery succeeded or failed. Click on any delivery to see the full request payload and response body for debugging.
SalesSheet.ai automatically retries failed deliveries using an exponential backoff schedule. After the initial failure, retries are attempted at 1 minute, 5 minutes, 30 minutes, 2 hours, and 24 hours. If all retry attempts fail, the delivery is marked as permanently failed and the event is logged in your webhook's failure history. After 50 consecutive failures, the webhook is automatically disabled and you will receive an email notification.
For high-reliability integrations, we recommend implementing idempotent processing on your server. Use the unique delivery_id included in each payload to detect and ignore duplicate deliveries that may occur during retry sequences.
Dica Pro
For maximum reliability, have your webhook endpoint immediately return a 200 response and process the payload asynchronously using a background job queue. This prevents timeouts caused by slow processing logic and ensures SalesSheet.ai does not unnecessarily retry deliveries. Tools like AWS SQS, RabbitMQ, or Redis queues work well for this pattern.
Importante Note
Webhook payloads may contain sensitive CRM data including contact names, email addresses, and deal values. Ensure your receiving endpoint uses HTTPS encryption, validates the webhook signature to prevent spoofing, and stores received data securely. Do not log full webhook payloads in plaintext in production environments. Review your organization's data handling policies before configuring webhooks that send CRM data to external systems.
O que Esperar
With webhooks configured, your external systems stay in sync with SalesSheet.ai in real time:
- Near-instant delivery: Webhook payloads are dispatched within seconds of the triggering event occurring in SalesSheet.ai.
- Structured JSON payloads: Every delivery contains the event type, timestamp, full resource data, and change details in a consistent JSON format.
- Automatic retries: Failed deliveries are retried up to 5 times over 24 hours using exponential backoff to handle temporary outages.
- Signature verification: Validate webhook authenticity using HMAC-SHA256 signatures to prevent unauthorized payloads from being processed.
- Delivery monitoring: Full delivery history with request and response details for easy debugging and auditing.
- Flexible event selection: Subscribe to exactly the events you need, from individual resource changes to broad catch-all subscriptions.
Solucao de Problemas
First, confirm the webhook is active (not paused or disabled) in Settings > Integracoes > Webhooks. Check that your endpoint URL is correct and publicly accessible - SalesSheet.ai cannot deliver to localhost, private IPs, or non-HTTPS URLs. Use the "Send Test Event" button to trigger a manual delivery and check your server logs. If your server is behind a firewall, you may need to whitelist SalesSheet.ai's IP addresses, which are listed in the webhook settings documentation.
SalesSheet.ai requires your endpoint to respond within 10 seconds. If your processing logic takes longer, restructure your endpoint to accept the payload immediately (return 200), then process it asynchronously using a background job or message queue. Check your server's response time and resource utilization - high server load can cause timeout failures. Also verify that your SSL certificate is valid and not expired, as certificate errors can cause connection timeouts.
Duplicates can occur when your endpoint takes too long to respond and SalesSheet.ai retries the delivery. Each payload includes a unique delivery_id field - implement idempotency checks in your processing logic by storing processed delivery IDs and skipping any duplicates. If you are consistently receiving duplicates, it may indicate your endpoint is responding too slowly. Optimize your response time or switch to asynchronous processing to prevent retry-triggered duplicates.