Webhooks
Configure outbound webhooks to send real-time notifications about database events, query results, and system activities
Webhooks
Webhooks enable MongoDash to send real-time HTTP notifications to external services when specific events occur, allowing you to build event-driven integrations and automation workflows.
Overview
Use webhooks to:
- Notify external systems - Send database change notifications to microservices
- Trigger workflows - Start automation in Zapier, Make, or n8n
- Alert on events - Send notifications to Slack, Teams, or PagerDuty
- Sync with external databases - Update search indexes, caches, or data warehouses
- Audit and compliance - Log events to external audit systems
Webhooks are available on all paid plans (Team, Business, and Enterprise). Real-time change stream webhooks require MongoDB 4.0+ with replica sets.
Creating a Webhook
Navigate to Automation > Webhooks in the workspace.
Click New Webhook to open the configuration dialog.
Configure basic settings:
- Name: Descriptive name for the webhook
- URL: Destination endpoint (https:// URLs only)
- Method: HTTP method (POST, PUT, PATCH)
- Event type: What triggers the webhook
Configure Headers (optional):
- Authorization tokens
- Content-Type
- Custom headers
Define the Payload template using variables and JSON formatting.
Set up Filters to control when the webhook fires (optional).
Click Create Webhook and test with a sample event.

Event Types
Database Events
Trigger webhooks on MongoDB operations:
Document Events:
document.inserted- New document createddocument.updated- Document modifieddocument.deleted- Document removeddocument.replaced- Document fully replaced
Collection Events:
collection.created- New collection createdcollection.dropped- Collection deletedcollection.renamed- Collection renamed
Database Events:
database.created- New database createddatabase.dropped- Database deleted
Query Events
Trigger on query execution:
query.executed- Any query completesquery.failed- Query execution failsquery.slow- Query exceeds performance thresholdscheduled_query.completed- Scheduled query finishesscheduled_query.failed- Scheduled query errors
Dashboard Events
Trigger on dashboard activities:
dashboard.created- New dashboard createddashboard.updated- Dashboard modifieddashboard.shared- Dashboard shared with usersdashboard.deleted- Dashboard removed
User Events
Trigger on user activities:
user.login- User signs inuser.logout- User signs outuser.invited- New user invited to workspaceuser.removed- User removed from workspaceuser.role_changed- User role modified
System Events
Trigger on system activities:
connection.created- New MongoDB connection addedconnection.failed- Connection attempt failsalert.triggered- Alert condition metexport.completed- Data export finishes

Payload Templates
Basic Payload
Send event data to your endpoint:
{
"event": "{{event.type}}",
"timestamp": "{{event.timestamp}}",
"workspace": "{{workspace.name}}",
"data": {
"collection": "{{event.collection}}",
"database": "{{event.database}}",
"operation": "{{event.operation}}"
}
}
Document Change Payload
Include full document details:
{
"event": "document.updated",
"timestamp": "{{event.timestamp}}",
"database": "{{event.database}}",
"collection": "{{event.collection}}",
"document": {
"before": {{event.document.before | json}},
"after": {{event.document.after | json}}
},
"updateDescription": {
"updatedFields": {{event.updateDescription.updatedFields | json}},
"removedFields": {{event.updateDescription.removedFields | json}}
},
"user": {
"email": "{{event.user.email}}",
"id": "{{event.user.id}}"
}
}
Query Result Payload
Send query results to external systems:
{
"query": {
"name": "{{query.name}}",
"filter": {{query.filter | json}},
"executionTime": "{{query.executionTime}}ms"
},
"results": {
"count": {{results.count}},
"documents": {{results.documents | json | limit: 100}}
},
"timestamp": "{{event.timestamp}}"
}
Slack-Compatible Payload
Format for Slack incoming webhooks:
{
"text": "Database Event: {{event.type}}",
"blocks": [
{
"type": "header",
"text": {
"type": "plain_text",
"text": "MongoDB Change Detected"
}
},
{
"type": "section",
"fields": [
{
"type": "mrkdwn",
"text": "*Database:*\n{{event.database}}"
},
{
"type": "mrkdwn",
"text": "*Collection:*\n{{event.collection}}"
},
{
"type": "mrkdwn",
"text": "*Operation:*\n{{event.operation}}"
},
{
"type": "mrkdwn",
"text": "*User:*\n{{event.user.email}}"
}
]
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*Document ID:* `{{event.documentId}}`"
}
}
]
}
Use the payload preview feature to see how your template renders with sample event data before activating the webhook.
Filtering Events
Collection Filters
Only trigger for specific collections:
{
"filter": {
"database": "production_db",
"collection": { "$in": ["users", "orders", "payments"] }
}
}
Operation Filters
Filter by operation type:
{
"filter": {
"operation": { "$in": ["insert", "update"] },
"database": "app_db"
}
}
Document Filters
Trigger only for documents matching criteria:
{
"filter": {
"collection": "orders",
"document.status": "completed",
"document.amount": { "$gte": 1000 }
}
}
User Filters
Filter by who performed the action:
{
"filter": {
"user.email": { "$regex": "@company.com$" },
"operation": "delete"
}
}
Time-Based Filters
Control when webhooks fire:
{
"filter": {
"time": {
"dayOfWeek": { "$in": [1, 2, 3, 4, 5] },
"hourOfDay": { "$gte": 9, "$lte": 17 }
}
}
}

Authentication
Bearer Token
Use Authorization header:
{
"headers": {
"Authorization": "Bearer {{secret:webhook_token}}",
"Content-Type": "application/json"
}
}
API Key
Send API key in header or query parameter:
{
"headers": {
"X-API-Key": "{{secret:api_key}}"
}
}
Basic Auth
Use HTTP Basic Authentication:
{
"headers": {
"Authorization": "Basic {{base64:username:password}}"
}
}
Custom Signature
Add HMAC signature for verification:
{
"headers": {
"X-Webhook-Signature": "{{hmac_sha256:payload:secret_key}}"
}
}
Store sensitive credentials in MongoDash secrets, not directly in webhook configurations. Use the {{secret:key_name}} syntax to reference secrets securely.
Retry and Error Handling
Retry Configuration
Configure automatic retries for failed deliveries:
{
"retryPolicy": {
"enabled": true,
"maxAttempts": 3,
"backoff": "exponential",
"initialDelay": "5s",
"maxDelay": "5m",
"retryOn": [500, 502, 503, 504, 429]
}
}
Timeout Settings
Set request timeout limits:
{
"timeout": "30s",
"connectTimeout": "5s"
}
Failure Notifications
Get notified when webhooks fail:
{
"onFailure": {
"notification": {
"email": ["admin@company.com"],
"subject": "Webhook Delivery Failed: {{webhook.name}}"
},
"pauseAfterFailures": 5
}
}
Dead Letter Queue Business
Store failed webhook payloads for retry:
{
"deadLetterQueue": {
"enabled": true,
"connection": "prod_cluster",
"database": "system",
"collection": "webhook_failures",
"retentionDays": 30
}
}
Real-Time Change Streams Business
Configuring Change Streams
Monitor MongoDB changes in real-time:
{
"eventType": "change_stream",
"source": {
"connection": "prod_cluster",
"database": "app_db",
"collection": "orders",
"changeStream": {
"fullDocument": "updateLookup",
"pipeline": [
{
"$match": {
"operationType": { "$in": ["insert", "update"] },
"fullDocument.status": "pending"
}
}
]
}
},
"webhookUrl": "https://api.example.com/order-webhook",
"bufferSize": 100,
"bufferTime": "5s"
}
Batching Changes
Send multiple changes in a single webhook:
{
"batching": {
"enabled": true,
"maxSize": 100,
"maxWait": "10s"
},
"payload": {
"events": {{events | json}},
"count": {{events.length}},
"timestamp": "{{batch.timestamp}}"
}
}

Integration Examples
Slack Notifications
Send notifications to Slack channels:
{
"name": "Production Errors to Slack",
"url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
"eventType": "query.failed",
"payload": {
"text": ":rotating_light: Query Failed in Production",
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*Query:* {{query.name}}\n*Error:* {{error.message}}\n*User:* {{user.email}}"
}
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": {
"type": "plain_text",
"text": "View Details"
},
"url": "{{query.url}}"
}
]
}
]
}
}
Zapier Integration
Trigger Zapier workflows:
{
"name": "New User to CRM",
"url": "https://hooks.zapier.com/hooks/catch/YOUR_ID/",
"eventType": "document.inserted",
"filter": {
"collection": "users"
},
"payload": {
"email": "{{document.email}}",
"name": "{{document.name}}",
"signupDate": "{{document.createdAt}}",
"plan": "{{document.subscription.plan}}"
}
}
Elasticsearch Sync
Update search index on document changes:
{
"name": "Sync to Elasticsearch",
"url": "https://elasticsearch.example.com/users/_doc/{{document._id}}",
"method": "PUT",
"eventType": "document.updated",
"filter": {
"collection": "users"
},
"headers": {
"Authorization": "ApiKey {{secret:elastic_api_key}}",
"Content-Type": "application/json"
},
"payload": {
"name": "{{document.name}}",
"email": "{{document.email}}",
"bio": "{{document.bio}}",
"indexed_at": "{{event.timestamp}}"
}
}
PagerDuty Alerts
Create incidents for critical events:
{
"name": "Database Errors to PagerDuty",
"url": "https://events.pagerduty.com/v2/enqueue",
"eventType": "alert.triggered",
"filter": {
"alert.severity": { "$in": ["critical", "high"] }
},
"payload": {
"routing_key": "{{secret:pagerduty_key}}",
"event_action": "trigger",
"payload": {
"summary": "{{alert.name}}",
"severity": "{{alert.severity}}",
"source": "MongoDash",
"custom_details": {
"database": "{{alert.database}}",
"collection": "{{alert.collection}}",
"threshold": "{{alert.threshold}}",
"current_value": "{{alert.value}}"
}
}
}
}
Monitoring Webhooks
Delivery Status
Track webhook delivery success:

Metrics and Logs
View detailed execution logs:
{
"webhookId": "wh_abc123",
"deliveries": [
{
"deliveryId": "del_xyz789",
"timestamp": "2024-02-24T10:15:32Z",
"status": "success",
"httpStatus": 200,
"responseTime": "145ms",
"attempt": 1,
"payload": { "..." },
"response": {
"status": 200,
"body": "{\"success\": true}"
}
},
{
"deliveryId": "del_xyz788",
"timestamp": "2024-02-24T10:10:15Z",
"status": "failed",
"httpStatus": 503,
"responseTime": "30002ms",
"attempt": 3,
"error": "Connection timeout after 30s",
"nextRetry": "2024-02-24T10:25:15Z"
}
],
"statistics": {
"totalDeliveries": 1523,
"successRate": "98.7%",
"avgResponseTime": "182ms",
"failureRate": "1.3%"
}
}
Alerting on Failures
Get notified of webhook issues:
{
"monitoring": {
"alertOnFailureRate": {
"threshold": 5,
"window": "1 hour",
"notification": ["admin@company.com"]
},
"alertOnSlowResponse": {
"threshold": "5s",
"notification": ["engineering@company.com"]
}
}
}
Security Best Practices
Webhook Security
- Use HTTPS only - Never send webhooks to HTTP endpoints
- Validate SSL certificates - Don't disable certificate verification
- Rotate secrets - Regularly update API keys and tokens
- Use signature verification - Add HMAC signatures for payload verification
- Limit payload size - Avoid sending large documents (use references instead)
IP Allowlisting Enterprise
Restrict webhook sources:
{
"ipAllowlist": [
"203.0.113.0/24",
"198.51.100.42"
]
}
Rate Limiting
Prevent webhook floods:
{
"rateLimits": {
"maxDeliveriesPerMinute": 100,
"maxDeliveriesPerHour": 5000
}
}
API Access
Manage webhooks programmatically:
# Create a new webhook
curl -X POST https://api.mongodash.com/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Order Updates",
"url": "https://api.example.com/webhook",
"eventType": "document.updated",
"filter": {"collection": "orders"}
}'
# Test a webhook
curl -X POST https://api.mongodash.com/v1/webhooks/wh_abc123/test \
-H "Authorization: Bearer YOUR_API_KEY"
# Get webhook delivery logs
curl -X GET https://api.mongodash.com/v1/webhooks/wh_abc123/deliveries \
-H "Authorization: Bearer YOUR_API_KEY"
Best Practices
Webhook Design
- Keep payloads small - Send IDs and let receiver fetch full data
- Use idempotency keys - Include unique IDs to prevent duplicate processing
- Version your webhooks - Include version info in payload
- Document payload schema - Maintain clear documentation for consumers
Reliability
- Implement retry logic - Handle temporary failures gracefully
- Monitor delivery rates - Set up alerts for high failure rates
- Use dead letter queues - Store failed deliveries for investigation
- Test endpoints - Verify webhooks before activation
Performance
- Use batching - Combine multiple events when possible
- Optimize filters - Reduce unnecessary webhook triggers
- Async processing - Design receivers to process webhooks asynchronously
- Monitor response times - Optimize slow webhook endpoints
What's Next?
- Scheduled Queries - Automate recurring queries
- Data Sync - Synchronize data between collections
- API Integration - Build custom integrations with the REST API