Webhooks

Receive real-time notifications when events happen in Genju.

How Webhooks Work

When an event fires, Genju sends a POST request to your URL with a JSON payload. Your server must return a 2xx response within 10 seconds.

Headers

X-Genju-Event	Event slug (e.g. contact.created)
X-Genju-Signature	HMAC-SHA256 signature for verification
X-Genju-Delivery	Unique delivery ID for deduplication

Retry Behaviour

Non-2xx or timeout = failed delivery. Retries at: 30 seconds, 5 minutes, 30 minutes. After 3 failures, the subscription is marked as failing and you receive an in-app notification.

Signature Verification

Every webhook is signed with HMAC-SHA256. Always verify the signature before processing any payload.

const crypto = require('crypto');

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

// Express handler:
app.post('/webhook', (req, res) => {
  const sig = req.headers['x-genju-signature'];
  if (!verifyWebhookSignature(req.body, sig, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  // Process event...
  res.status(200).json({ received: true });
});