Skip to main content

Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur in your Synaptis account. Instead of polling the API, webhooks push data to your endpoint as events happen.

Webhook Endpoint
POST https://your-server.com/webhooks/synaptis

Event Types

Subscribe to specific event types to receive only the notifications relevant to your integration.

lead.submitted

Fired when a new lead is submitted to the system

lead.verified

Fired when lead verification is complete

lead.distributed

Fired when a lead is routed to a buyer

delivery.success

Fired when a lead is successfully delivered to a buyer

delivery.failed

Fired when lead delivery fails after all retries

ping.received

Fired when a ping request is received in ping/post flow

bid.won

Fired when your bid wins an auction

Payload Structure

All webhook payloads follow a consistent structure with event metadata and type-specific data.

Example Payload: lead.verified
{
  "id": "evt_abc123xyz",
  "type": "lead.verified",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "lead_id": "lead_456def",
    "verification_status": "passed",
    "quality_score": 92,
    "checks": {
      "email": { "valid": true, "deliverable": true },
      "phone": { "valid": true, "type": "mobile" },
      "address": { "valid": true, "standardized": true },
      "duplicate": { "is_duplicate": false },
      "fraud": { "risk_score": 12, "risk_level": "low" }
    },
    "routing_decision": "approved",
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "api_version": "2024-01-01"
}

Setting Up Webhooks

Configure webhook endpoints through the API or your dashboard.

POST /v1/webhooksCreate Webhook
curl -X POST https://api.synaptis.io/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/synaptis",
    "events": [
      "lead.verified",
      "delivery.success",
      "delivery.failed"
    ],
    "description": "Production webhook endpoint"
  }'
Response
{
  "id": "wh_abc123",
  "url": "https://your-server.com/webhooks/synaptis",
  "events": ["lead.verified", "delivery.success", "delivery.failed"],
  "secret": "whsec_xyz789...",
  "status": "active",
  "created": "2024-01-15T10:00:00Z"
}

Signature Verification

Always verify webhook signatures to ensure requests are from Synaptis. The signature is included in theX-Synaptis-Signature header.

Node.js Verification Example
import crypto from 'crypto';

function verifyWebhookSignature(payload, signature, secret) {
  const timestamp = signature.split(',')[0].split('=')[1];
  const hash = signature.split(',')[1].split('=')[1];
  
  const signedPayload = `${timestamp}.${JSON.stringify(payload)}`;
  const expectedHash = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(hash),
    Buffer.from(expectedHash)
  );
}

Retry Policy

If your endpoint returns a non-2xx status code or times out, we'll retry the webhook with exponential backoff.

AttemptDelayTotal Time
1st retry1 minute1 minute
2nd retry5 minutes6 minutes
3rd retry30 minutes36 minutes
4th retry2 hours~2.5 hours
5th retry (final)24 hours~26.5 hours

Best Practices

Respond quickly

Return a 200 status within 5 seconds. Process webhooks asynchronously.

Handle duplicates

Use the event ID for idempotency. The same event may be delivered multiple times.

Verify signatures

Always validate the webhook signature to prevent spoofed requests.

AuthenticationRate Limits

Demo Platform: This is a demonstration of our custom development capabilities. We build tailored solutions for your specific needs.

Schedule Demo