Webhooks

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

curl -X POST "https://api.engagefabric.com/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

Event	Description
`player.created`	New player identified
`player.updated`	Player data changed
`player.xp_granted`	Player received XP
`player.level_up`	Player reached new level
`player.currency_granted`	Player received currency
`player.badge_earned`	Player earned a badge

Quest Events

Event	Description
`quest.started`	Player started a quest
`quest.progress`	Quest progress updated
`quest.completed`	Player completed a quest

Adventure Events

Event	Description
`adventure.started`	Player started an adventure
`adventure.completed`	Player completed an adventure

Leaderboard Events

Event	Description
`leaderboard.rank_changed`	Player’s rank changed significantly
`leaderboard.new_leader`	New #1 on leaderboard

Lobby Events

Event	Description
`lobby.created`	New lobby created
`lobby.started`	Lobby game started
`lobby.ended`	Lobby 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
  }
}

Field	Description
`id`	Unique event ID (for idempotency)
`type`	Event type
`projectId`	Your project ID
`createdAt`	ISO 8601 timestamp
`data`	Event-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

Always verify signatures

Never process webhooks without verifying the signature first.

Use HTTPS

Always use HTTPS endpoints for webhooks.

Respond quickly

Return 200 within 30 seconds. Process events asynchronously.

Handle duplicates

Use event IDs to deduplicate. Webhooks may be retried.

Retry Policy

Failed webhooks are retried with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 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.

Getting Started

Guides

Core Concepts

API Reference

Endpoints

SDKs

Resources

Setting Up Webhooks

1. Create a Webhook Endpoint

2. Register the Webhook

Webhook Events

Player Events

Quest Events

Adventure Events

Leaderboard Events

Lobby Events

Webhook Payload

Security

Signature Verification

Best Practices

Retry Policy

Managing Webhooks

List Webhooks

Update Webhook

Delete Webhook

Test Webhook

Webhook Logs

​Setting Up Webhooks

​1. Create a Webhook Endpoint

​2. Register the Webhook

​Webhook Events

​Player Events

​Quest Events

​Adventure Events

​Leaderboard Events

​Lobby Events

​Webhook Payload

​Security

​Signature Verification

​Best Practices

​Retry Policy

​Managing Webhooks

​List Webhooks

​Update Webhook

​Delete Webhook

​Test Webhook

​Webhook Logs

Setting Up Webhooks

1. Create a Webhook Endpoint

2. Register the Webhook

Webhook Events

Player Events

Quest Events

Adventure Events

Leaderboard Events

Lobby Events

Webhook Payload

Security

Signature Verification

Best Practices

Retry Policy

Managing Webhooks

List Webhooks

Update Webhook

Delete Webhook

Test Webhook

Webhook Logs