Access with your multiplai account in https://api.deepworkzone.ai

💡

Note: The domain still in API this will moved into app.deepworkzone.ai as we move forward

Webhooks Documentation

Overview

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.

Key Features

Statistics Dashboard

Monitor webhook performance with real-time metrics:

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
Organization	Sessions within your organization	Team-specific workflows
User	Sessions where you're a participant	Personal notifications

Configuration

Creating a Webhook

Navigate to Settings → Webhooks

Click Create new

Configure the following:

Required Fields

Event

Currently supported: session.completed

Triggered when a session participant completes their session

URL

Your endpoint that will receive webhook POST requests

Must be a valid HTTPS URL (recommended for security)

Example: https://api.yourapp.com/webhooks/deepworkzone

Level

global: Receives all session completion events

org: Receives events for your organization's sessions

user: Receives events only when you're a participant

Secret

32+ character string for HMAC-SHA256 signature verification

Auto-generated if not provided

Used to verify webhook authenticity (see Security section)

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

Extract the signature from the X-Webhook-Signature header

Compute HMAC-SHA256 of the raw request body using your webhook secret

Compare the computed signature with the received signature

Example (PHP)

Response Requirements

Your webhook endpoint must:

Respond quickly (< 10 seconds)

Timeout is set to 10 seconds

Process asynchronously if needed

Return appropriate status codes

200-299: Success (logged as successful delivery)

400-599: Error (logged as failed delivery)

Handle retries gracefully

Webhooks are not automatically retried

Implement idempotency using timestamp or participant_id

Testing Webhooks

Test Endpoint

Send a test webhook to verify your endpoint configuration:

Navigate to webhook detail page

Click Test Webhook

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

Viewing Logs

Access detailed delivery logs:

Webhook Detail Page: View logs for a specific webhook

Webhook Logs Page: View all logs across your webhooks

Log Information

Each log entry contains:

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 delivery attempt

Best Practices

Endpoint Design

Use HTTPS: Secure your webhook endpoint with TLS

Verify signatures: Always validate the X-Webhook-Signature header

Return quickly: Respond within 10 seconds, queue heavy processing

Log everything: Keep audit logs of received webhooks

Handle duplicates: Use participant_id + timestamp for idempotency

Monitoring

Monitor webhook success rates in the dashboard

Set up alerts for high failure rates

Review logs regularly for patterns or issues

Test webhooks after endpoint changes

Troubleshooting

Common Issues

Webhook Not Triggering

Check:

Webhook is set to is_active: true

Event type matches (session.completed)

Level configuration is correct:

global: Always triggers

org: Organization ID matches session

user: User ID matches participant

Delivery Failures

Possible causes:

Endpoint timeout (> 10 seconds)

Invalid SSL certificate

Endpoint returning 4xx/5xx status codes

Network connectivity issues

Solutions:

Optimize endpoint response time

Ensure valid SSL certificate

Check endpoint logs for errors

Verify firewall/network configuration

Signature Verification Fails

Check:

Using correct webhook secret

Computing HMAC on raw request body (not parsed JSON)

Using sha256 algorithm

Comparing signatures with timing-safe function

Limits & Quotas

Timeout: 10 seconds per webhook delivery

Retries: No automatic retries (implement your own if needed)

Concurrent Webhooks: Processed via queue system

Log Retention: Logs are retained indefinitely (monitor storage)

Future Events

Currently in development:

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

Support

For webhook-related issues:

Check webhook logs for delivery details

Verify endpoint configuration and security

Test with the built-in test function

Review this documentation for best practices

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

Webhooks

Login#

Webhooks Documentation#

Webhooks Documentation#

Overview#

Key Features#

Statistics Dashboard#

Webhook Levels#

Configuration#

Creating a Webhook#

Required Fields#

Webhook Payload#

Event: session.completed#

Payload Fields#

Security#

Signature Verification#

Verification Steps#

Example (PHP)#

Response Requirements#

Testing Webhooks#

Test Endpoint#

Test Payload#

Webhook Logs#

Viewing Logs#

Log Information#

Best Practices#

Endpoint Design#

Monitoring#

Troubleshooting#

Common Issues#

Webhook Not Triggering#

Delivery Failures#

Signature Verification Fails#

Limits & Quotas#

Future Events#

Support#

Changelog#

Current Version#

Coming Soon#

Login

Webhooks Documentation

Webhooks Documentation

Overview

Key Features

Statistics Dashboard

Webhook Levels

Configuration

Creating a Webhook

Required Fields

Webhook Payload

Event: `session.completed`

Payload Fields

Security

Signature Verification

Verification Steps

Example (PHP)

Response Requirements

Testing Webhooks

Test Endpoint

Test Payload

Webhook Logs

Viewing Logs

Log Information

Best Practices

Endpoint Design

Monitoring

Troubleshooting

Common Issues

Webhook Not Triggering

Delivery Failures

Signature Verification Fails

Limits & Quotas

Future Events

Support

Changelog

Current Version

Coming Soon