Skip to main content
Version: Next

Webhook Configuration

This guide explains how to configure webhook endpoints in the Beedeez platform to receive real-time event notifications.

Accessing Webhook Configuration​

Webhook endpoints are configured through the Beedeez back office. You'll need administrator privileges to access and manage webhook settings.

Creating a Webhook Endpoint​

To create a new webhook endpoint, you'll need to provide the following information:

Required Fields​

Name​

A human-readable name to identify this webhook endpoint. This helps you manage multiple webhooks.

Example: "Production Certificate Notifications" or "HR System Integration"

URL​

The HTTPS endpoint URL where Beedeez will send webhook notifications. This must be a publicly accessible URL that can receive POST requests.

Requirements:

  • Must use HTTPS (HTTP is not supported for security)
  • Must be publicly accessible
  • Should respond within 5 seconds (configurable)
  • Must return HTTP 2xx status code for successful receipt

Example: https://api.yourcompany.com/webhooks/beedeez

Event Types​

Select which events should trigger this webhook. You can subscribe to one or multiple event types. See the Event Types Reference for a complete list.

Currently Available Events:

  • certificate_completed - When a user completes a certificate
  • certificate_expired - When a certificate expires

Example: ["certificate_completed", "certificate_expired"]

Optional Configuration​

Enabled​

Toggle to enable or disable the webhook without deleting the configuration.

Default: true

Timeout (ms)​

Maximum time in milliseconds to wait for your endpoint to respond before considering the request failed.

Default: 5000 (5 seconds) Range: 1000-30000 ms

Custom Headers​

Additional HTTP headers to include with each webhook request. Useful for passing API keys, correlation IDs, or other metadata.

Example:

{
    "X-Custom-ID": "your-identifier",
    "X-Environment": "production"
}

Authentication​

Configure how Beedeez should authenticate with your webhook endpoint. See Authentication Options for detailed information.

Available Methods:

  • None (not recommended for production)
  • Bearer Token
  • Basic Authentication
  • API Key
  • Custom Header

Configuration Example​

Here's a complete example of a webhook endpoint configuration:

{
    "name": "Production Certificate Webhook",
    "url": "https://api.yourcompany.com/webhooks/beedeez/certificates",
    "enabled": true,
    "eventTypes": ["certificate_completed", "certificate_expired"],
    "auth": {
        "authType": "bearer_token",
        "token": "your-secret-bearer-token"
    },
    "timeoutMs": 5000,
    "customHeaders": {
        "X-Webhook-Source": "beedeez",
        "X-Environment": "production"
    }
}

Webhook Delivery​

Request Format​

Beedeez sends webhook notifications as HTTP POST requests with:

  • Method: POST
  • Content-Type: application/json
  • Body: JSON payload with event data
  • Headers: Authentication headers + custom headers

Response Requirements​

Your endpoint should:

  1. Respond Quickly: Return a response within the configured timeout (default 5 seconds)
  2. Return Success Status: Return HTTP status code 2xx (200-299) to acknowledge receipt
  3. Handle Idempotency: Be prepared to receive the same event multiple times

Successful Response Example:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "received": true,
  "message": "Webhook processed successfully"
}

Retry Logic​

If your endpoint doesn't respond successfully, Beedeez automatically retries the webhook delivery:

  • Maximum Attempts: 100 retries
  • Retry Interval: Fixed 6 seconds between attempts
  • Total Retry Duration: Up to 10 minutes
  • Retry Conditions: Any HTTP status code outside 2xx range or network timeout

Retry Behavior:

  • 1st retry: After 6 seconds
  • 2nd retry: After 12 seconds
  • 3rd retry: After 18 seconds
  • ... continues every 6 seconds up to 100 attempts

Queue Configuration​

Webhooks are processed through a dedicated queue system:

  • Concurrency: Up to 5 parallel webhook requests
  • Queue Name: webhook-notification
  • Processing: Asynchronous with automatic retry

Best Practices​

Security​

  • ✅ Always use HTTPS endpoints
  • ✅ Implement authentication (Bearer token or API key recommended)
  • ✅ Validate webhook signatures if available
  • ✅ Whitelist Beedeez IP addresses if possible

Reliability​

  • ✅ Design idempotent webhook handlers
  • ✅ Store webhook events for audit and replay
  • ✅ Return 2xx status codes only after successful processing
  • ✅ Use a queue or background job for long-running operations

Performance​

  • ✅ Respond within 5 seconds
  • ✅ Process webhooks asynchronously
  • ✅ Monitor webhook endpoint health
  • ✅ Set up alerts for failed webhooks

Testing​

  • ✅ Test with sample payloads before going live
  • ✅ Verify authentication works correctly
  • ✅ Test retry behavior by simulating failures
  • ✅ Monitor logs for the first few days after setup

Monitoring Webhook Status​

The webhook configuration tracks delivery statistics:

  • Created At: When the webhook was configured
  • Last Triggered: Timestamp of the most recent webhook delivery
  • Success Count: Number of successful deliveries
  • Failure Count: Number of failed deliveries (after all retries)

Monitor these metrics to ensure your webhooks are functioning correctly.

Troubleshooting​

Webhooks Not Being Received​

  1. Check Endpoint Accessibility: Ensure your URL is publicly accessible via HTTPS
  2. Verify Event Types: Confirm you're subscribed to the correct event types
  3. Check Enabled Status: Ensure the webhook is enabled
  4. Review Authentication: Verify authentication credentials are correct
  5. Check Firewall Rules: Ensure your firewall allows incoming requests from Beedeez

Webhooks Timing Out​

  1. Optimize Response Time: Ensure your endpoint responds within the timeout period
  2. Use Background Processing: Move heavy processing to background jobs
  3. Increase Timeout: Adjust the timeout setting if needed (up to 30 seconds)
  4. Check Server Resources: Ensure your server has adequate resources

Duplicate Webhooks​

This is expected behavior due to retry logic. Design your webhook handler to be idempotent:

  • Use unique event IDs to detect duplicates
  • Store processed webhook IDs in a database
  • Skip processing if the event was already handled

Next Steps​