Docs/Data & Analytics/Webhooks

Webhooks

Set up real-time event forwarding via webhooks to integrate Ilara with your existing tools.

8 min read

Overview

Webhooks allow Ilara to send real-time HTTP requests to your endpoints when specific events occur. Use webhooks to integrate with external systems, trigger workflows, or build custom functionality.

Creating Webhooks

Dashboard

Go to Settings → Integrations → Webhooks
Click "Add Webhook"
Enter your endpoint URL
Select trigger events
Configure authentication (optional)
Test and save

API

Create Webhook via API

json

POST /v1/integrations/webhooks
{
  class="code-string">"name": class="code-string">"Purchase Notification",
  class="code-string">"url": class="code-string">"https:class="code-commentclass="code-string">">//your-server.com/webhooks/ilara",
  class="code-string">"events": [class="code-string">"purchase_complete", class="code-string">"subscription_start"],
  class="code-string">"secret": class="code-string">"whsec_your_signing_secret",
  class="code-string">"enabled": true,
  class="code-string">"headers": {
    class="code-string">"X-Custom-Header": class="code-string">"value"
  },
  class="code-string">"retry_policy": {
    class="code-string">"max_retries": 3,
    class="code-string">"backoff": class="code-string">"exponential"
  }
}

Webhook Events

Player Events

Event	Trigger
`player.created`	New player identified
`player.updated`	Player attributes changed
`player.lifecycle_changed`	Lifecycle stage transition
`player.segment_entered`	Player joined segment
`player.segment_exited`	Player left segment

Game Events

Event	Trigger
`event.*`	Any tracked event (wildcard)
`event.purchase_complete`	Specific event type
`event.session_end`	Session ended

System Events

Event	Trigger
`flag.evaluated`	Feature flag evaluation
`campaign.triggered`	Retention campaign triggered
`churn.risk_high`	Player became high churn risk

Webhook Payload

Example Payload

json

{
  class="code-string">"id": class="code-string">"evt_123abc",
  class="code-string">"type": class="code-string">"event.purchase_complete",
  class="code-string">"timestamp": class="code-string">"2025-01-25T14:30:00Z",
  class="code-string">"data": {
    class="code-string">"player_id": class="code-string">"550e8400-e29b-41d4-a716-446655440000",
    class="code-string">"external_id": class="code-string">"player_123",
    class="code-string">"event_name": class="code-string">"purchase_complete",
    class="code-string">"properties": {
      class="code-string">"product_id": class="code-string">"gem_pack_100",
      class="code-string">"amount": 9.99,
      class="code-string">"currency": class="code-string">"USD"
    }
  },
  class="code-string">"metadata": {
    class="code-string">"webhook_id": class="code-string">"whk_xyz",
    class="code-string">"delivery_attempt": 1
  }
}

Security

Signature Verification

All webhooks include a signature header for verification:

Verify Signature (Node.js)

javascript

const crypto = require(class="code-string">'crypto');
 
function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac(class="code-string">'sha256', secret)
    .update(payload)
    .digest(class="code-string">'hex');
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(class="code-string">`sha256=${expectedSignature}`)
  );
}
 
class=class="code-string">"code-comment">// In your endpoint handler
app.post(class="code-string">'/webhooks/ilara', (req, res) => {
  const signature = req.headers[class="code-string">'x-ilara-signature'];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );
 
  if (!isValid) {
    return res.status(401).send(class="code-string">'Invalid signature');
  }
 
  class=class="code-string">"code-comment">// Process webhook...
  res.status(200).send(class="code-string">'OK');
});

IP Allowlisting

Ilara webhooks originate from these IP ranges:

52.x.x.x/24
34.x.x.x/24

Contact support for current IP ranges if you need to allowlist.

Retry Policy

Failed webhooks are automatically retried:

Attempt	Delay	Total Time
1	Immediate	0
2	1 minute	1 min
3	5 minutes	6 min
4	30 minutes	36 min
5	2 hours	2h 36min

Failure Responses

Webhooks are considered failed if they return 4xx/5xx status codes, timeout (30s), or if the connection fails.

Event Filtering

Filter which events trigger your webhook:

Filtered Webhook

json

{
  class="code-string">"name": class="code-string">"High-Value Purchases",
  class="code-string">"url": class="code-string">"https:class="code-commentclass="code-string">">//your-server.com/webhooks/purchases",
  class="code-string">"events": [class="code-string">"event.purchase_complete"],
  class="code-string">"filters": {
    class="code-string">"properties.amount": { class="code-string">"gte": 50 },
    class="code-string">"properties.currency": { class="code-string">"eq": class="code-string">"USD" }
  }
}
 
class=class="code-string">"code-comment">// Only triggers for purchases >= $50 USD

Monitoring

Monitor webhook health in Settings → Webhooks → [Webhook] → Logs:

Delivery History: Recent deliveries with status
Success Rate: Percentage of successful deliveries
Average Latency: Response time of your endpoint
Error Details: Full request/response for debugging

Best Practices

Respond quickly: Return 200 within 5s, process async
Verify signatures: Always validate webhook authenticity
Handle duplicates: Use event ID for idempotency
Queue processing: Don't block webhook response
Monitor failures: Alert on webhook delivery issues

Next Steps

Data Export — Batch export to warehouses
Events API — Query events via API
Multi-Channel — Trigger notifications

Data Export

Authentication