Skip to content

Webhooks Feature

Overview

Webhooks enable businesses to receive real-time event notifications from ConnectGain to external systems. Webhooks support HMAC signature verification, event filtering, delivery logging, and comprehensive testing capabilities.

Features

1. Webhook Configuration

Configuration Options: - Webhook name - Webhook URL (HTTPS required) - Event subscriptions - Secret key (for HMAC signatures) - Active/inactive status

2. Available Events

Contact Events: - contact.created - New contact created - contact.updated - Contact information updated - contact.assigned - Contact assigned to user

Deal Events: - deal.created - New deal created - deal.updated - Deal information updated - deal.stage.changed - Deal moved to different stage - deal.assigned - Deal assigned to user

Conversation Events: - conversation.created - New conversation started - conversation.assigned - Conversation assigned to user - conversation.status.changed - Conversation status changed

Message Events: - message.received - New message received - message.sent - Message sent successfully - message.delivered - Sent message delivered to recipient - message.read - Sent message read by recipient - message.failed - Message failed to send

Broadcast Events: - broadcast.response - Contact replied to a broadcast/campaign message

Meeting Events: - zoom.recording.completed - Zoom cloud recording finished processing

3. Event Filtering

Filtering Features: - Subscribe to specific events - Multiple event selection - Event-based routing - Selective notifications

4. HMAC Signature Verification

Security Features: - Optional secret key configuration - HMAC-SHA256 signatures - Signature verification - Secure webhook delivery

5. Delivery Logging

Logging Features: - All delivery attempts logged - Response codes tracked - Error messages recorded - Delivery timestamps - Success/failure tracking

6. Webhook Testing

Testing Features: - Test webhook button - Test payload generation - Delivery verification - Response validation

7. Webhook Management

Management Features: - Create webhooks - Edit webhook configuration - Delete webhooks - Enable/disable webhooks - View webhook logs - Retry failed deliveries

8. Request Format

HTTP Method: POST

Headers: - Content-Type: application/json - X-Webhook-Event: event.type - X-Webhook-Timestamp: ISO timestamp - X-Webhook-Signature: HMAC-SHA256 (if secret configured)

Body: 

{
 "event": "contact.created",
 "timestamp": "2025-01-15T10:30:00Z",
 "data": {
 "id": "uuid",
 "first_name": "John",
 "last_name": "Doe",...
 }
}

Use Cases

Use Case 1: Sync Contacts to External CRM

Scenario: Business wants to sync new contacts to external CRM system.

Steps: 1. Go to Settings → Webhooks 2. Click "Create Webhook" 3. Enter name: "CRM Sync" 4. Enter URL: https://crm.example.com/webhook 5. Select events: contact.created, contact.updated 6. Set secret key (optional) 7. Activate webhook 8. Test webhook 9. Verify delivery in logs 10. Create test contact 11. Verify webhook received

Expected Outcome: New contacts automatically synced to external CRM.

Use Case 2: Notify on Deal Stage Changes

Scenario: Business wants to notify external system when deal moves to "Won" stage.

Steps: 1. Create webhook 2. Set URL: https://api.example.com/deals 3. Select event: deal.stage.changed 4. Configure secret key 5. Activate webhook 6. Test webhook 7. Change deal stage to "Won" 8. Verify webhook received 9. Check delivery logs

Expected Outcome: External system notified when deal won.

Use Case 3: Real-Time Message Notifications

Scenario: Business wants real-time notifications for new messages.

Steps: 1. Create webhook 2. Set URL: https://notifications.example.com/webhook 3. Select events: message.received 4. Configure secret key 5. Activate webhook 6. Receive test message 7. Verify webhook triggered 8. Check delivery logs 9. Verify notification sent

Expected Outcome: Real-time notifications for new messages.

Test Cases

Test Case 1: Create Webhook

Test: Verify webhook creation

Steps: 1. Go to Settings → Webhooks 2. Click "Create Webhook" 3. Enter name and URL 4. Select events 5. Set secret key (optional) 6. Activate webhook 7. Save webhook 8. Verify webhook appears in list 9. Verify configuration saved

Expected Result: Webhook created successfully

Test Case 2: Test Webhook

Test: Verify webhook testing

Steps: 1. Create webhook 2. Click "Test" button 3. Verify test payload sent 4. Check webhook.site or endpoint 5. Verify payload received 6. Check delivery logs 7. Verify response code

Expected Result: Webhook test successful

Test Case 3: Event Triggering

Test: Verify event triggering

Steps: 1. Create webhook with contact.created event 2. Activate webhook 3. Create new contact 4. Verify webhook triggered 5. Check delivery logs 6. Verify payload correct 7. Verify event type matches

Expected Result: Webhook triggered on event

Test Case 4: HMAC Signature

Test: Verify HMAC signature

Steps: 1. Create webhook with secret key 2. Trigger webhook 3. Extract signature from headers 4. Verify signature using secret 5. Check signature matches 6. Test with invalid secret 7. Verify signature fails

Expected Result: HMAC signature verification works

Test Case 5: Delivery Logging

Test: Verify delivery logging

Steps: 1. Create webhook 2. Trigger multiple events 3. View webhook logs 4. Verify all attempts logged 5. Check response codes 6. Verify timestamps 7. Check error messages

Expected Result: All deliveries logged correctly

API Integration

Create Webhook

Endpoint: POST /rest/v1/webhook_configurations

Request: 

{
 "organization_id": "org-uuid",
 "name": "CRM Sync",
 "url": "https://crm.example.com/webhook",
 "events": ["contact.created", "contact.updated"],
 "secret": "your-secret-key",
 "is_active": true
}

Get Webhooks

Endpoint: GET /rest/v1/webhook_configurations

Query Parameters: - organization_id - Filter by organization - is_active - Filter by status

Get Webhook Logs

Endpoint: GET /rest/v1/webhook_logs

Query Parameters: - webhook_id - Filter by webhook - status - Filter by delivery status - created_at - Filter by date

Best Practices

  1. Webhook Design
  2. Use HTTPS URLs only
  3. Implement idempotency
  4. Handle retries gracefully

  5. Respond quickly (< 5 seconds)

  6. Security

  7. Use HMAC signatures
  8. Verify signatures server-side
  9. Use secure secret keys

  10. Rotate secrets regularly

  11. Error Handling

  12. Log all webhook deliveries
  13. Monitor failure rates
  14. Implement retry logic

  15. Alert on persistent failures

  16. Performance

  17. Respond quickly
  18. Process asynchronously
  19. Handle timeouts
  20. Monitor webhook performance

Troubleshooting

Webhook Not Triggering

Issue: Webhook not receiving events

Solutions: - Check webhook status (must be active) - Verify event subscriptions - Check webhook logs - Verify event occurred

Delivery Failures

Issue: Webhook deliveries failing

Solutions: - Check endpoint URL - Verify endpoint accessible - Check response codes - Review error messages - Test endpoint manually

Signature Verification Fails

Issue: HMAC signature not matching

Solutions: - Verify secret key correct - Check signature calculation - Verify header name - Review signature format

Last Updated: January 2025