Skip to main content

Webhooks

Use webhooks to trigger external systems when events occur in Realtor Bot.

Overview​

Webhooks allow Realtor Bot to send real-time notifications to your external systems when specific events happen, enabling powerful integrations and custom workflows.

How Webhooks Work​

graph LR
    A[Event Occurs] --> B[Realtor Bot]
    B --> C[Webhook Triggered]
    C --> D[HTTP POST Request]
    D --> E[Your Server]
    E --> F[Process Data]

Available Events​

Bot Events​

  • bot.created - New bot created
  • bot.updated - Bot settings changed
  • bot.activated - Bot went live
  • bot.deactivated - Bot paused

Conversation Events​

  • conversation.started - New conversation initiated
  • conversation.message - New message in conversation
  • conversation.ended - Conversation completed

Lead Events​

  • lead.created - New lead captured
  • lead.qualified - Lead qualified by bot
  • lead.scored - Lead score updated

Appointment Events​

  • appointment.scheduled - Appointment booked
  • appointment.rescheduled - Appointment time changed
  • appointment.cancelled - Appointment cancelled
  • appointment.completed - Appointment finished

Email Events​

  • email.received - Email received
  • email.sent - Email sent by bot
  • email.opened - Email opened by recipient
  • email.clicked - Link clicked in email

Setup​

1. Create Webhook Endpoint​

Create an endpoint on your server to receive webhook data:

// Example Node.js endpoint
app.post('/webhooks/realtorbot', (req, res) => {
  const event = req.body;
  
  console.log('Event type:', event.type);
  console.log('Event data:', event.data);
  
  // Process the event
  handleEvent(event);
  
  // Respond with 200 OK
  res.status(200).send('OK');
});

2. Configure Webhook in Realtor Bot​

  1. Go to Settings → Webhooks
  2. Click "Add Webhook"
  3. Enter your endpoint URL
  4. Select events to subscribe to
  5. (Optional) Add secret key for verification
  6. Save and test

3. Verify Webhook Signature​

Verify webhook authenticity using the signature:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return hash === signature;
}

app.post('/webhooks/realtorbot', (req, res) => {
  const signature = req.headers['x-realtorbot-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  if (!verifyWebhook(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook...
});

Webhook Payload​

Standard Format​

All webhooks follow this format:

{
  "id": "evt_1234567890",
  "type": "lead.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    // Event-specific data
  }
}

Example Payloads​

Lead Created:

{
  "id": "evt_abc123",
  "type": "lead.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "leadId": "lead_xyz789",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "source": "website_form",
    "score": 75
  }
}

Appointment Scheduled:

{
  "id": "evt_def456",
  "type": "appointment.scheduled",
  "timestamp": "2024-01-15T11:00:00Z",
  "data": {
    "appointmentId": "appt_123",
    "contactId": "contact_456",
    "propertyId": "prop_789",
    "date": "2024-01-20",
    "time": "14:00",
    "duration": 60,
    "type": "showing"
  }
}

Retry Logic​

If your endpoint fails to respond with 200 OK:

  1. Immediate retry - Retry after 1 second
  2. Second retry - Retry after 5 seconds
  3. Third retry - Retry after 30 seconds
  4. Final retry - Retry after 5 minutes

After 4 failed attempts, the webhook is marked as failed.

Best Practices​

1. Respond Quickly​

Return 200 OK immediately, then process the webhook asynchronously.

app.post('/webhooks/realtorbot', async (req, res) => {
  // Respond immediately
  res.status(200).send('OK');
  
  // Process asynchronously
  processWebhook(req.body).catch(console.error);
});

2. Handle Duplicates​

Webhooks may be sent multiple times. Use the event ID to deduplicate:

const processedEvents = new Set();

function handleEvent(event) {
  if (processedEvents.has(event.id)) {
    return; // Already processed
  }
  
  processedEvents.add(event.id);
  // Process event...
}

3. Verify Signatures​

Always verify webhook signatures to ensure authenticity.

4. Log Webhooks​

Keep logs of received webhooks for debugging and auditing.

5. Monitor Failures​

Set up alerts for webhook failures to catch issues quickly.

Testing​

Test Webhook​

Use the "Test Webhook" button in settings to send a test payload:

{
  "id": "evt_test_123",
  "type": "test",
  "timestamp": "2024-01-15T12:00:00Z",
  "data": {
    "message": "This is a test webhook"
  }
}

Local Testing​

Use tools like ngrok to test webhooks locally:

# Start ngrok
ngrok http 3000

# Use the ngrok URL as your webhook endpoint
https://abc123.ngrok.io/webhooks/realtorbot

Troubleshooting​

Webhooks Not Received​

  • Check endpoint URL is correct
  • Verify server is accessible
  • Check firewall settings
  • Review webhook logs

Signature Verification Failing​

  • Verify secret key is correct
  • Check payload is not modified
  • Ensure proper encoding

Duplicate Webhooks​

  • Implement idempotency using event ID
  • Check retry logic
  • Review processing time

Next Steps​