Webhooks

Webhooks enable real-time HTTP callbacks when specific events occur in your DeepWorkZone sessions. Configure webhook endpoints to receive event notifications and integrate with external systems.

---

Overview

Webhooks push event data to your own HTTP endpoint whenever a supported event fires. This allows external systems to react to session activity without polling the API.

---

Admin Panel

Configure and manage webhooks directly from the DeepWorkZone admin panel:

Environment	Admin Panel URL
Production	api.deepworkzone.ai
Development	api-dev.deepworkzone.ai

Navigate to Settings → Webhooks to create, test, and monitor your webhook integrations.

---

Statistics Dashboard

Monitor webhook performance with real-time metrics:

Metric	Description
Total Sent	Total number of webhook deliveries attempted
Success	Successfully delivered webhooks (2xx responses)
Failed	Failed delivery attempts (non-2xx or timeout)
Success Rate	Percentage of successful deliveries

---

Webhook Levels

Control webhook scope with three access levels:

Level	Scope	Use Case
global	All sessions across the platform	System-wide integrations
org	Sessions within your organization	Team-specific workflows
user	Sessions where you are a participant	Personal notifications

---

Configuration

Creating a Webhook

1. Navigate to Settings → Webhooks
2. Click Create new
3. Configure the following fields:

Required Fields

Field	Description
Event	Currently supported: session.completed — triggered when a session participant completes a session
URL	Your HTTPS endpoint that will receive webhook POST requests. Example: https://api.yourapp.com/webhooks/deepworkzone
Level	global · org · user — controls which sessions trigger this webhook (see Webhook Levels above)
Secret	32+ character string for HMAC-SHA256 signature verification. Auto-generated if not provided.

---

Webhook Payload

Event: session.completed

Sent when a participant completes a session.

{
  "event": "participation.completed",
  "participant_id": 123,
  "multiplai_id": 71123,
  "session_id": 456,
  "status": "completed",
  "actual_score": 95.5,
  "presence_score": 98.2,
  "timestamp": "2024-01-15T14:30:00+00:00"
}

Payload Fields

Field	Type	Description
event	string	Event type identifier
participant_id	integer	ID of the session participant
multiplai_id	integer	GoTeam / Multiplai primary user ID
session_id	integer	ID of the completed session
status	string	Participant completion status
actual_score	float	Participant's performance score
presence_score	float	Participant's presence / attendance score
timestamp	string	ISO 8601 timestamp of the event

---

Security

Signature Verification

All webhook requests include an X-Webhook-Signature header containing an HMAC-SHA256 signature.

Verification Steps

1. Extract the signature from the X-Webhook-Signature header
2. Compute HMAC-SHA256 of the raw request body using your webhook secret
3. Compare the computed signature with the received signature using a timing-safe comparison function

Use sha256 algorithm and compare on the raw body, not the parsed JSON.

---

Response Requirements

Your endpoint must:

1. Respond quickly (< 10 seconds) — process asynchronously if needed
2. Return appropriate status codes
   • 200–299 → logged as successful delivery
   • 400–599 → logged as failed delivery
3. Handle retries gracefully — webhooks are not automatically retried; implement idempotency using timestamp or participant_id

---

Testing Webhooks

1. Navigate to the webhook detail page
2. Click Test Webhook
3. Check the logs for delivery status

Test Payload

{
  "event": "session.completed",
  "timestamp": "2024-01-15T14:30:00+00:00",
  "test": true,
  "data": {
    "message": "This is a test webhook event"
  }
}

---

Webhook Logs

Each log entry contains:

Field	Description
Event	The event type that triggered the webhook
Status	success or failed
Status Code	HTTP response code from your endpoint
Payload	The JSON payload sent
Response	Response body from your endpoint
Error Message	Error details (if failed)
Sent At	Timestamp of the delivery attempt

---

Best Practices

1. Use HTTPS — secure your webhook endpoint with TLS
2. Verify signatures — always validate the X-Webhook-Signature header
3. Return quickly — respond within 10 seconds, queue heavy processing
4. Log everything — keep audit logs of received webhooks
5. Handle duplicates — use participant_id + timestamp for idempotency

---

Troubleshooting

Webhook Not Triggering

Check that:

• Webhook is_active is set to true
• Event type matches session.completed
• Level configuration is correct:
  • global → always triggers
  • org → organization ID must match the session
  • user → user ID must match the participant

Delivery Failures

Possible causes:

• Endpoint timeout (> 10 seconds)
• Invalid SSL certificate
• Endpoint returning 4xx/5xx status codes
• Network connectivity issues

Signature Verification Fails

Check that:

• You are using the correct webhook secret
• HMAC is computed on the raw request body (not parsed JSON)
• You are using the sha256 algorithm
• You are comparing signatures with a timing-safe function

---

Limits & Quotas

Constraint	Value
Timeout	10 seconds per delivery
Retries	No automatic retries
Log Retention	Indefinite (monitor storage usage)

---

Future Events

Currently in development:

Event	Description
session.created	Triggered when a new session is created
session.deleted	Triggered when a session is deleted
session.started	Triggered when a session begins
participant.joined	Triggered when a user joins a session

---

Changelog

Current Version

• session.completed event support
• Three-level access control (global, org, user)
• HMAC-SHA256 signature verification
• Webhook testing functionality
• Detailed logging and statistics

Coming Soon

• Additional event types
• Webhook retry mechanism
• Rate limiting configuration
• Custom headers support