UltraReach.ai

Webhooks

UltraReach.ai uses webhooks to notify your application when events happen in real-time. This guide explains how to implement, secure, and manage webhooks effectively.

Available Events

lead.qualified

Triggered when a lead meets qualification criteria

property.matched

Triggered when properties are matched to a lead

message.received

Triggered when a new message is received

analysis.completed

Triggered when market analysis is complete

Event Payload

{
  "id": "evt_123456789",
  "type": "lead.qualified",
  "created": "2025-02-07T02:55:00Z",
  "data": {
    "lead_id": "lead_987654321",
    "score": 85,
    "qualification_type": "hot",
    "triggers": ["budget_match", "high_engagement"]
  },
  "version": "2024-01-01"
}

Implementation Guide

1. Register Endpoint

POST /api/v1/webhooks
{
  "url": "https://your-domain.com/webhook",
  "events": ["lead.qualified", "property.matched"],
  "description": "Production webhook handler"
}

2. Verify Signatures

const signature = req.headers['x-ultrareach-signature'];
const timestamp = req.headers['x-ultrareach-timestamp'];
const payload = req.body;

const isValid = verifyWebhookSignature(
  payload,
  signature,
  timestamp,
  WEBHOOK_SECRET
);

3. Handle Events

app.post('/webhook', async (req, res) => {
  const event = req.body;
  
  switch(event.type) {
    case 'lead.qualified':
      await handleQualifiedLead(event.data);
      break;
    case 'property.matched':
      await handlePropertyMatch(event.data);
      break;
    default:
      console.log(`Unhandled event: ${event.type}`);
  }

  res.json({ received: true });
});

4. Implement Retry Logic

// Exponential backoff
const retryWebhook = async (event, attempt = 1) => {
  try {
    await processWebhook(event);
  } catch (error) {
    if (attempt <= 5) {
      const delay = Math.pow(2, attempt) * 1000;
      await wait(delay);
      return retryWebhook(event, attempt + 1);
    }
    throw error;
  }
};

Security Best Practices

  • •Always verify webhook signatures
  • •Use HTTPS endpoints only
  • •Implement request timeouts
  • •Rotate webhook secrets regularly

Monitoring

  • •Track delivery success rates
  • •Monitor response times
  • •Set up failure alerts
  • •Log all webhook activities

Troubleshooting

  • •Check webhook logs
  • •Verify endpoint availability
  • •Test with webhook simulator
  • •Review response codes

Testing Tools

Webhook Tester

Test your webhook endpoints with sample events

Event Viewer

View and filter webhook delivery history

Signature Validator

Verify webhook signature implementation

Debug Console

Debug webhook delivery issues in real-time