Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur in your MarketSage account.

Setting Up Webhooks

1. Go to Settings → Webhooks
2. Click Add Webhook
3. Enter your endpoint URL
4. Select the events you want to receive
5. Save the webhook

Available Events

Webhook Payload

Webhooks are sent as HTTP POST requests with JSON body:

{
  "event": "contact.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "id": "contact_abc123",
    "email": "user@example.com",
    "name": "John Doe",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Verifying Webhooks

Each webhook includes a signature header for verification:

X-MarketSage-Signature: sha256=abc123...

Verify the signature using your webhook secret:

const crypto = require('crypto');

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

  return signature === `sha256=${expectedSignature}`;
}

Handling Webhooks

// Express.js example
app.post('/webhooks/marketsage', (req, res) => {
  const signature = req.headers['x-marketsage-signature'];

  if (!verifyWebhook(JSON.stringify(req.body), signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const { event, data } = req.body;

  switch (event) {
    case 'contact.created':
      console.log('New contact:', data.email);
      break;
    case 'lead.qualified':
      console.log('Qualified lead:', data.id);
      break;
  }

  res.status(200).send('OK');
});

Retry Policy

If your endpoint returns a non-2xx status, we retry:

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

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

Next Steps