Webhooks

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

Registering Webhooks

Register a webhook endpoint in your dashboard or via the API:

curl -X POST "https://api.serply.io/v1/webhooks" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks",
    "events": ["search.completed", "search.failed"]
  }'

Consuming Webhooks

Your webhook endpoint should:

1. Accept POST requests
2. Verify the webhook signature
3. Process the event data
4. Return a 200 status code

Example webhook handler:

app.post('/webhooks', (req, res) => {
  const signature = req.headers['x-serply-signature'];
  const isValid = verifySignature(req.body, signature);
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = req.body;
  // Process the event
  processEvent(event);
  
  res.status(200).send('OK');
});

Event Types

• search.completed - A search request completed successfully
• search.failed - A search request failed
• quota.exceeded - API quota limit reached

Security

Always verify webhook signatures to ensure requests are from Serply:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(payload)).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}