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

Creating a Webhook

Event Types

Database Events

Trigger webhooks on MongoDB operations:

Document Events:

• document.inserted - New document created
• document.updated - Document modified
• document.deleted - Document removed
• document.replaced - Document fully replaced

Collection Events:

• collection.created - New collection created
• collection.dropped - Collection deleted
• collection.renamed - Collection renamed

Database Events:

• database.created - New database created
• database.dropped - Database deleted

Query Events

Trigger on query execution:

• query.executed - Any query completes
• query.failed - Query execution fails
• query.slow - Query exceeds performance threshold
• scheduled_query.completed - Scheduled query finishes
• scheduled_query.failed - Scheduled query errors

Dashboard Events

Trigger on dashboard activities:

• dashboard.created - New dashboard created
• dashboard.updated - Dashboard modified
• dashboard.shared - Dashboard shared with users
• dashboard.deleted - Dashboard removed

User Events

Trigger on user activities:

• user.login - User signs in
• user.logout - User signs out
• user.invited - New user invited to workspace
• user.removed - User removed from workspace
• user.role_changed - User role modified

System Events

Trigger on system activities:

• connection.created - New MongoDB connection added
• connection.failed - Connection attempt fails
• alert.triggered - Alert condition met
• export.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}}`"
      }
    }
  ]
}

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

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

1. Use HTTPS only - Never send webhooks to HTTP endpoints
2. Validate SSL certificates - Don't disable certificate verification
3. Rotate secrets - Regularly update API keys and tokens
4. Use signature verification - Add HMAC signatures for payload verification
5. 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

1. Keep payloads small - Send IDs and let receiver fetch full data
2. Use idempotency keys - Include unique IDs to prevent duplicate processing
3. Version your webhooks - Include version info in payload
4. Document payload schema - Maintain clear documentation for consumers

Reliability

1. Implement retry logic - Handle temporary failures gracefully
2. Monitor delivery rates - Set up alerts for high failure rates
3. Use dead letter queues - Store failed deliveries for investigation
4. Test endpoints - Verify webhooks before activation

Performance

1. Use batching - Combine multiple events when possible
2. Optimize filters - Reduce unnecessary webhook triggers
3. Async processing - Design receivers to process webhooks asynchronously
4. 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