Skip to content

Webhooks and Events

This document describes how ConnectSoft systems expose and consume webhooks and events. It is written for architects and engineers building webhook integrations and event-driven systems.

ConnectSoft platforms support both webhooks (external systems calling into our endpoints) and events (internal asynchronous messaging). Understanding when to use each pattern is crucial for building effective integrations.

Note

Webhooks are for external systems calling into ConnectSoft. Events are for internal or cross-service asynchronous messaging. Use the right pattern for your use case.

When to Use Webhooks

Use webhooks when:

  • External Systems Need Real-Time Notifications - External systems need immediate updates
  • Push-Based Integration - You need to push data to external systems
  • Event-Driven External Integration - External systems are event-driven
  • Low Latency Requirements - Real-time updates are critical
  • External System Cannot Poll - External system doesn't support polling

Examples: - Identity Platform notifying external systems of user events - Audit Platform sending audit events to SIEM systems - Bot Platform receiving messages from external channels

When to Use Events

Use events when:

  • Internal Service Communication - Communication between internal services
  • Asynchronous Processing - Non-blocking, asynchronous operations
  • Decoupled Architecture - Services need to be decoupled
  • High Throughput - High-volume event processing
  • Multiple Consumers - Multiple services need to react to same event

Examples: - Domain events within a microservice - Integration events between microservices - Event-driven workflows and orchestration

See: Event-Driven Mindset for event-driven principles.

Exposing Webhooks from Platforms

Identity Platform Webhooks

Event Types: - User registered - User authenticated - User updated - Token issued - Token revoked

Webhook Structure: - Endpoint - Configurable webhook URL per tenant - Authentication - Signature validation (HMAC) - Payload - JSON payload with event data - Retry Logic - Automatic retry on failure

Example Payload: 

{
  "eventType": "user.registered",
  "timestamp": "2026-01-01T10:30:00Z",
  "tenantId": "tenant-123",
  "data": {
    "userId": "user-456",
    "email": "user@example.com"
  }
}

Audit Platform Webhooks

Event Types: - Audit event created - Audit event updated - Retention policy triggered - Compliance alert

Webhook Structure: - Endpoint - Configurable webhook URL per tenant - Authentication - API key or OAuth2 - Payload - Audit event data - Batching - Optional batching for high-volume events

Config Platform Webhooks

Event Types: - Configuration updated - Feature flag changed - Tenant settings changed

Webhook Structure: - Endpoint - Configurable webhook URL per tenant - Authentication - Signature validation - Payload - Configuration change data - Idempotency - Idempotency keys for safe retries

Bot Platform Webhooks

Event Types: - Message received - Conversation started - Conversation ended - Channel event

Webhook Structure: - Endpoint - Channel-specific webhook endpoints - Authentication - Channel-specific auth (Slack, Teams, etc.) - Payload - Message and context data - Response - Bot response in webhook response

Consuming External Webhooks

Webhook Ingestion Pattern

flowchart LR
    A[External System] -->|Webhook| B[Webhook Endpoint]
    B --> C[Validation]
    C --> D[Queue]
    D --> E[Processor]
    E --> F[Business Logic]
    F --> G[Response]

    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#e8f5e9
    style D fill:#fff4e1
    style E fill:#e8f5e9
    style F fill:#f3e5f5
Hold "Alt" / "Option" to enable pan & zoom

Implementation Steps

  1. Webhook Endpoint - Expose HTTP endpoint for webhook calls
  2. Validation - Validate webhook signature/authentication
  3. Queue - Queue webhook payload for async processing
  4. Processor - Process webhook payload
  5. Response - Return HTTP 200 OK immediately
  6. Error Handling - Handle failures with retries and DLQ

Security Considerations

  • Signature Validation - Validate HMAC signatures
  • IP Whitelisting - Whitelist known webhook sources
  • Rate Limiting - Prevent webhook abuse
  • Authentication - Require authentication tokens
  • Idempotency - Handle duplicate webhooks

See: Security & Compliance for security guidelines.

Event Bus Integration Patterns

Internal Event Flow

flowchart LR
    A[Service A] -->|Domain Event| B[Event Bus]
    B --> C[Service B]
    B --> D[Service C]
    B --> E[Integration Service]
    E --> F[External API]

    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#e8f5e9
    style D fill:#e8f5e9
    style E fill:#fff4e1
    style F fill:#f3e5f5
Hold "Alt" / "Option" to enable pan & zoom

Event Types

  • Domain Events - Events within a bounded context
  • Integration Events - Events across bounded contexts
  • System Events - Infrastructure and platform events

See: Event-Driven Mindset for event types and patterns.

Event Bus Technologies

  • MassTransit - Messaging abstraction library
  • Azure Service Bus - Primary message broker
  • RabbitMQ - Alternative message broker (self-hosted)

See: Technology Stack for technology details.

Event Patterns

  • Pub/Sub - Publish events, multiple subscribers
  • Point-to-Point - Direct message delivery
  • Request/Response - Synchronous request/response over events
  • Saga - Long-running distributed transactions

Tip

Best Practices: 1. Use Events for Internal - Events for service-to-service communication 2. Use Webhooks for External - Webhooks for external system integration 3. Validate Webhooks - Always validate webhook signatures 4. Queue Webhooks - Queue webhook processing for reliability 5. Idempotent Processing - Handle duplicate events/webhooks safely