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

  1. Navigate to Webhooks: Go to your BCMS dashboard → Settings → Webhooks

  2. Location: The webhook management interface is located at /settings/webhooks in your BCMS project

CleanShot 2025-07-06 at 12.45.25@2x.jpg

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

  1. Click "Edit" next to any webhook in the list

  2. Modify the URL, description, or triggers as needed

  3. Click "Update webhook" to save changes

Deleting webhooks

  1. Open the webhook for editing

  2. Click the "Delete webhook" button

  3. Confirm the deletion in the confirmation dialog

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

  1. Invalid URL: Ensure HTTPS is used and URL is publicly accessible

  2. Webhook not triggering: Check that the correct triggers are selected

  3. Delivery failures: Verify your endpoint is responding correctly

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