Setting Up Webhooks for Real-Time Event Tracking

Learn how to configure webhooks in Admin to receive instant, reliable notifications about system events, user actions, and data changes directly to your endpoints.

Prerequisites

Admin API access key (found in Settings > API Keys)
A publicly accessible HTTPS endpoint (localhost/tunneling not supported)
Basic understanding of JSON payloads and HTTP POST requests

Step 1: Configure Your Endpoint

Navigate to your Admin dashboard and go to Settings > Integrations > Webhooks. Click Create Webhook and provide the following:

Endpoint URL: The HTTPS URL that will receive event payloads
Webhook Name: A descriptive identifier (e.g., "Production Event Handler")
HTTP Method: Always POST

Verify HTTPS Requirement

Admin enforces strict HTTPS validation. Self-signed certificates are rejected. Ensure your endpoint responds to POST /webhook with a 200 OK status.

ℹ️

Development Testing

Use tools like ngrok, localtunnel, or webhook.site to expose local servers during development.

Step 2: Select Event Types

Choose which events trigger webhook deliveries. You can subscribe to individual events or event groups.

Event Category	Event Type	Description
Users	`user.created`	New user registered in the system
Users	`user.updated`	User profile or permissions modified
Orders	`order.completed`	Payment confirmed and order finalized
System	`system.alert`	Critical system notification or threshold breach
Integrations	`integration.connected`	Third-party service successfully linked

Step 3: Security & Signature Verification

All webhook payloads are signed using HMAC-SHA256 to ensure authenticity. Verify signatures before processing data.

JavaScript (Node.js)

const crypto = require('crypto');

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

// Usage in Express:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-admin-signature'];
  if (!signature || !verifyWebhookSignature(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process event...
  res.status(200).send('Received');
});

⚠️

Security Best Practice

Always use constant-time comparison for signature verification to prevent timing attacks. Never expose your webhook secret in client-side code.

Payload Structure

Every webhook payload follows a consistent schema:

JSON

{
  "id": "evt_8f3a9c2d1e5b7",
  "type": "user.created",
  "timestamp": "2025-01-15T14:32:00Z",
  "data": {
    "user_id": "usr_9x2k4m7",
    "email": "developer@example.com",
    "role": "admin",
    "created_via": "api"
  },
  "metadata": {
    "source": "web",
    "ip_address": "203.0.113.42"
  }
}

Retry Policy & Delivery Guarantees

Admin uses an exponential backoff strategy for failed deliveries:

Attempt 1: Immediate delivery
Attempt 2: 15 seconds
Attempt 3: 2 minutes
Attempt 4: 10 minutes
Attempt 5: 30 minutes
Attempt 6+: Hourly for up to 24 hours

Non-2xx responses trigger retries. Idempotency keys are included in the Idempotency-Key header to prevent duplicate processing.

Testing & Verification

Trigger a Test Event

After configuration, click Send Test Event in the Admin dashboard. Monitor your server logs or use a webhook inspector tool to verify receipt.

cURL

curl -X POST https://your-domain.com/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": true, "event": "webhook.configured"}'

✅

Success Indicators

Your endpoint should return 200 OK within 3 seconds. Check Admin's webhook activity log for delivery status and response times.

Troubleshooting

Issue	Probable Cause	Solution
Signature mismatch	Modified payload or incorrect secret	Verify raw body parsing; ensure secret matches dashboard
Timeout errors	Slow processing or heavy DB queries	Respond immediately, queue processing asynchronously
SSL/TLS handshake failure	Self-signed cert or outdated TLS version	Use valid CA-signed certificates; enable TLS 1.2+
Duplicate events	Network timeout before 200 response	Implement idempotency checks using event IDs

Frequently Asked Questions

How many webhooks can I create?

Admin supports up to 50 active webhook endpoints per workspace. Additional endpoints require enterprise plan approval.

Are webhooks ordered?

Yes. Events are delivered in chronological order per endpoint. If a retry occurs, it's inserted into the queue at the correct timestamp position.

What happens if my server goes down?

Admin caches events for 24 hours. Once your endpoint resumes accepting connections, queued events are replayed automatically.