Skip to main content
Webhooks allow you to receive HTTP callbacks when specific events occur in your EngageFabric project.
Webhooks are available on Pro and Enterprise plans. WebSocket subscriptions provide similar functionality for real-time client applications.

​
Setting Up Webhooks

​
1. Create a Webhook Endpoint

Create an HTTPS endpoint on your server to receive webhook events: 
// Express.js example
app.post('/webhooks/engagefabric', express.json(), (req, res) => {
  const event = req.body;

  // Verify signature
  const signature = req.headers['x-engagefabric-signature'];
  if (!verifySignature(event, signature)) {
    return res.status(401).send('Invalid signature');
  }

  // Process event
  switch (event.type) {
    case 'player.level_up':
      handleLevelUp(event.data);
      break;
    case 'quest.completed':
      handleQuestCompleted(event.data);
      break;
  }

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

​
2. Register the Webhook

Register your endpoint in the Admin Console or via API: 
curl -X POST "https://api.engagefabric.cloud/api/v1/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/engagefabric",
    "events": ["player.level_up", "quest.completed"],
    "secret": "your-webhook-secret"
  }'

​
Webhook Events

​
Player Events

EventDescription
player.createdNew player identified
player.updatedPlayer data changed
player.level_upPlayer reached new level
player.badge_earnedPlayer earned a badge

​
Quest Events

EventDescription
quest.startedPlayer started a quest
quest.progressQuest progress updated
quest.completedPlayer completed a quest

​
Adventure Events

EventDescription
adventure.startedPlayer started an adventure
adventure.completedPlayer completed an adventure

​
Leaderboard Events

EventDescription
leaderboard.rank_changedPlayer’s rank changed significantly
leaderboard.new_leaderNew #1 on leaderboard

​
Lobby Events

EventDescription
lobby.createdNew lobby created
lobby.startedLobby game started
lobby.endedLobby closed

​
Webhook Payload

All webhook payloads follow this structure: 
{
  "id": "evt_abc123",
  "type": "player.level_up",
  "projectId": "proj_xyz",
  "createdAt": "2025-01-21T10:00:00Z",
  "data": {
    "playerId": "player_123",
    "previousLevel": 4,
    "newLevel": 5,
    "xp": 500
  }
}
FieldDescription
idUnique event ID (for idempotency)
typeEvent type
projectIdYour project ID
createdAtISO 8601 timestamp
dataEvent-specific payload

​
Security

​
Signature Verification

All webhooks include a signature header for verification: 
X-EngageFabric-Signature: sha256=abc123...
Verify the signature: 
const crypto = require('crypto');

function verifySignature(payload, signature) {
  const secret = process.env.WEBHOOK_SECRET;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

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

​
Best Practices

Never process webhooks without verifying the signature first.
Always use HTTPS endpoints for webhooks.
Return 200 within 30 seconds. Process events asynchronously.
Use event IDs to deduplicate. Webhooks may be retried.

​
Retry Policy

Failed webhooks are retried with exponential backoff:
AttemptDelay
1Immediate
21 minute
35 minutes
430 minutes
52 hours
After 5 failed attempts, the webhook is marked as failed.

​
Managing Webhooks

​
List Webhooks

GET /api/v1/webhooks

​
Update Webhook

PATCH /api/v1/webhooks/{webhookId}

​
Delete Webhook

DELETE /api/v1/webhooks/{webhookId}

​
Test Webhook

Send a test event to verify your endpoint: 
POST /api/v1/webhooks/{webhookId}/test

​
Webhook Logs

View webhook delivery logs in the Admin Console:
  • Delivery status (success, failed, pending)
  • Response code and body
  • Retry count
  • Event payload
Use webhook logs to debug integration issues and monitor delivery health.