Webhooks

Receive real-time notifications when events occur in Iverton AI.

Overview

Webhooks send HTTP POST requests to your endpoint when events happen, enabling real-time integrations.

Setting Up Webhooks

Creating a Webhook

1. Go to Settings → Webhooks
2. Click Add Webhook
3. Enter your endpoint URL
4. Select events to subscribe
5. Click Create

Webhook Configuration

{
  "url": "https://yourapp.com/webhooks/iverton",
  "events": [
    "contact.created",
    "campaign.sent",
    "deal.updated"
  ],
  "secret": "whsec_xxxxxxxxxxxxx"
}

Webhook Payload

All webhooks send this structure:

{
  "id": "evt_123abc",
  "type": "contact.created",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "id": "con_456def",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }
}

Available Events

Contact Events

Event	Description
contact.created	New contact added
contact.updated	Contact modified
contact.deleted	Contact removed
contact.subscribed	Contact opted in
contact.unsubscribed	Contact opted out

Campaign Events

Event	Description
campaign.created	Campaign created
campaign.scheduled	Campaign scheduled
campaign.sent	Campaign sent
campaign.completed	Campaign finished

Email Events

Event	Description
email.delivered	Email delivered
email.opened	Email opened
email.clicked	Link clicked
email.bounced	Email bounced
email.complained	Spam complaint

Deal Events

Event	Description
deal.created	Deal created
deal.updated	Deal modified
deal.stage_changed	Deal moved stages
deal.won	Deal marked won
deal.lost	Deal marked lost

Client Events

Event	Description
client.created	Client created
client.updated	Client modified
client.deleted	Client removed

Verifying Webhooks

Verify webhook authenticity using the signature header.

Signature Header

X-Iverton-Signature: sha256=xxxxxxxxxxxxxxx

Verification Code

Node.js:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

Python:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(
        signature,
        f"sha256={expected}"
    )

Responding to Webhooks

Success Response

Return 2xx status to acknowledge receipt:

HTTP/1.1 200 OK

Retry Policy

Failed webhooks are retried:

• 1st retry: 1 minute
• 2nd retry: 5 minutes
• 3rd retry: 30 minutes
• 4th retry: 2 hours
• 5th retry: 24 hours

After 5 failures, webhook is disabled.

Best Practices

Do's

• Respond quickly (< 5 seconds)
• Return 200 immediately, process async
• Verify signatures
• Handle duplicates idempotently
• Log webhook events

Don'ts

• Don't do heavy processing synchronously
• Don't ignore signature verification
• Don't return errors for processed events

Example Handler

app.post('/webhooks/iverton', (req, res) => {
  // Verify signature first
  const signature = req.headers['x-iverton-signature'];
  if (!verifyWebhook(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Acknowledge immediately
  res.status(200).send('OK');

  // Process asynchronously
  processWebhookAsync(req.body);
});

async function processWebhookAsync(event) {
  switch (event.type) {
    case 'contact.created':
      await handleNewContact(event.data);
      break;
    case 'deal.won':
      await handleWonDeal(event.data);
      break;
    // ... handle other events
  }
}

Testing Webhooks

Webhook Tester

1. Go to Settings → Webhooks
2. Select a webhook
3. Click Send Test
4. Choose event type
5. View delivery results

Using ngrok

For local development:

ngrok http 3000
# Use the ngrok URL as your webhook endpoint

Webhook Logs

View webhook delivery history:

• Delivery status
• Response code
• Response time
• Request/response bodies

---

Return to API Overview →