> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engagefabric.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Configure EngageFabric webhooks for real-time event notifications. Set up HMAC-signed callbacks for player actions, level-ups, and quest completions.

Webhooks allow you to receive HTTP callbacks when specific events occur in your EngageFabric project.

<Note>
  Webhooks are available on Pro and Enterprise plans. WebSocket subscriptions
  provide similar functionality for real-time client applications.
</Note>

## Setting Up Webhooks

### 1. Create a Webhook Endpoint

Create an HTTPS endpoint on your server to receive webhook events:

```javascript theme={null}
// 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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```javascript theme={null}
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

<AccordionGroup>
  <Accordion title="Always verify signatures">
    Never process webhooks without verifying the signature first.
  </Accordion>

  <Accordion title="Use HTTPS">
    Always use HTTPS endpoints for webhooks.
  </Accordion>

  <Accordion title="Respond quickly">
    Return 200 within 30 seconds. Process events asynchronously.
  </Accordion>

  <Accordion title="Handle duplicates">
    Use event IDs to deduplicate. Webhooks may be retried.
  </Accordion>
</AccordionGroup>

***

## 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

```bash theme={null}
GET /api/v1/webhooks
```

### Update Webhook

```bash theme={null}
PATCH /api/v1/webhooks/{webhookId}
```

### Delete Webhook

```bash theme={null}
DELETE /api/v1/webhooks/{webhookId}
```

### Test Webhook

Send a test event to verify your endpoint:

```bash theme={null}
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

<Tip>
  Use webhook logs to debug integration issues and monitor delivery health.
</Tip>