Webhooks
Webhooks in BCMS allow you to receive real-time notifications when specific events occur in your content management system. This enables you to integrate BCMS with external services, trigger automated workflows, and keep your applications synchronized with content changes.
Accessing webhooks
Navigate to Webhooks: Go to your BCMS dashboard → Settings → Webhooks
Location: The webhook management interface is located at /settings/webhooks in your BCMS project
Creating a new webhook
Step 1: Access the create form
Click the "Add new webhook" button in the webhooks list view
This will open the webhook creation form
Step 2: Configure webhook settings
Webhook URL (Required)
Field: Webhook URL
Format: Must be a valid HTTPS URL
Example: https://example.com/bcms/webhook
Requirements:
Must use HTTPS protocol
Cannot be a relative path (starting with /)
Cannot contain thebcms.com domains
Must be a publicly accessible endpoint
Description (Optional)
Field: Webhook description
Purpose: Helps you identify the webhook's purpose
Example: "Used to trigger build on Netlify" or "Sync content to external database"
Triggers (Required)
Field: Webhook triggers
Type: Multi-select dropdown
Description: "Code will be executed only when a webhook of this type occurs"
Step 3: Select event triggers
BCMS supports the following event scopes and types:
Available event scopes:
apiKey: API key management events
entry: Content entry events
template: Template management events
user: User management events
entryStatus: Entry status change events
group: Group management events
language: Language management events
media: Media file events
widgets: Widget management events
Available event types:
created: When a new item is created
updated: When an existing item is modified
deleted: When an item is deleted
Trigger format:
Each trigger follows the format: scope:type
Examples:
entry:created - Triggers when a new entry is created
media:updated - Triggers when a media file is updated
user:deleted - Triggers when a user is deleted
Step 4: Save the webhook
Click "Add webhook" to create the webhook
The system will validate your inputs and create the webhook if all requirements are met
Managing existing webhooks
Viewing webhooks
The webhooks list shows all configured webhooks
Each webhook displays:
URL
Description
Last updated timestamp
Edit action button
Editing webhooks
Click "Edit" next to any webhook in the list
Modify the URL, description, or triggers as needed
Click "Update webhook" to save changes
Deleting webhooks
Open the webhook for editing
Click the "Delete webhook" button
Confirm the deletion in the confirmation dialog
Warning: This action is irreversible
Webhook payload and security
HTTP request details
When a webhook is triggered, BCMS sends a POST request with:
Headers:
Content-Type: application/json
X-Bcms-Webhook-Timestamp: Unix timestamp
X-Bcms-Webhook-Nonce: Random 4-byte hex string
X-Bcms-Webhook-Signature: HMAC-SHA256 signature
Body:
JSON payload containing the event data
The exact structure depends on the event scope and type
Security features
HTTPS Required: All webhook URLs must use HTTPS
Signature Verification: Each webhook includes a cryptographic signature
Unique Secret: Each webhook has a unique secret for signature generation
Timestamp Validation: Includes timestamp for replay attack prevention
Use cases and examples
1. Content deployment
Trigger: entry:updated, entry:created
Use Case: Automatically trigger builds on platforms like Netlify, Vercel, or GitHub Actions when content changes
2. External database sync
Trigger: entry:created, entry:updated, entry:deleted
Use Case: Keep external databases synchronized with BCMS content
3. Notification systems
Trigger: entry:created
Use Case: Send notifications to Slack, Discord, or email when new content is published
4. Media processing
Trigger: media:created
Use Case: Automatically process uploaded images or videos through external services
5. User management
Trigger: user:created, user:deleted
Use Case: Sync user data with external authentication systems
6. API key management
Trigger: apiKey:created, apiKey:deleted
Use Case: Monitor and log API key usage and changes
Best Practices
1. URL Configuration
Use HTTPS endpoints only
Ensure your endpoint can handle POST requests
Implement proper error handling (return 2xx status codes)
Set appropriate timeouts (BCMS has a default timeout)
2. Security
Verify webhook signatures to ensure authenticity
Use the timestamp to prevent replay attacks
Implement rate limiting on your webhook endpoint
Store webhook secrets securely
3. Reliability
Make your webhook endpoint idempotent
Implement retry logic for failed webhook deliveries
Log webhook events for debugging
Monitor webhook delivery success rates
4. Performance
Process webhooks asynchronously when possible
Keep webhook processing time under 30 seconds
Use webhook queues for high-volume scenarios
Limitations and Considerations
Account limits
Free accounts have webhook limits
Upgrade your account for additional webhook capacity
The system will show upgrade prompts when limits are reached
Technical limitations
Webhook URLs must be publicly accessible
Maximum payload size limits may apply
Webhook delivery is not guaranteed (implement retry logic)
Failed webhooks are logged but not retried automatically
Error handling
BCMS will log webhook delivery failures
Your endpoint should return appropriate HTTP status codes
Implement proper error handling in your webhook receiver
Troubleshooting
Common issues
Invalid URL: Ensure HTTPS is used and URL is publicly accessible
Webhook not triggering: Check that the correct triggers are selected
Delivery failures: Verify your endpoint is responding correctly
Signature verification: Use the webhook secret to verify signatures
Testing webhooks
Use tools like webhook.site for testing
Implement logging in your webhook receiver
Monitor webhook delivery in your application logs