Webhook Ingestion

Webhook ingestion enables real-time event capture from push-based platforms like Slack, Microsoft Teams, GitHub, Stripe, and any service that sends HTTP webhooks.

Architecture

External Platform → [POST /api/v1/webhooks/{platform}] → ingestion-service
    → Kafka topic: {tenantId}.webhook.{platform}
        → Flink stream job → Iceberg table

Unlike batch connectors (Airbyte pulls on a schedule), webhook ingestion receives events as they happen.

Supported Platforms

Setting Up Slack Integration

Step 1: Configure Slack App

In your Slack App settings:

• Go to Event Subscriptions
• Set Request URL: https://api.matih.ai/api/v1/webhooks/slack
• Matih automatically handles the URL verification challenge

Step 2: Subscribe to Events

Select which events to receive:

• message.channels — Messages in public channels
• message.groups — Messages in private channels
• reaction_added — Emoji reactions
• member_joined_channel — Channel joins

Step 3: Create Stream to Materialize

POST /api/v1/streams
{
  "name": "slack-events",
  "topics": ["{tenantId}.webhook.slack"],
  "targetTable": "slack_events",
  "valueFormat": "JSON"
}
POST /api/v1/streams/{id}/start

Event Enrichment

All webhook events are enriched with:

{
  "eventId": "uuid",
  "tenantId": "your-tenant-id",
  "platform": "slack",
  "eventType": "message",
  "receivedAt": "2026-03-18T10:00:00Z",
  "payload": { /* original webhook body */ }
}

Setting Up Microsoft Teams

Step 1: Register Bot

In Azure Portal → Bot Channels Registration:

• Set Messaging endpoint: https://api.matih.ai/api/v1/webhooks/teams

Step 2: Handle Activities

Teams sends Bot Framework activities:

• message — Chat messages
• conversationUpdate — Members added/removed
• messageReaction — Reactions

RBAC

Security

• All webhooks require X-Tenant-Id header for tenant isolation
• Platform name validated against ^[a-z0-9_-]+$ pattern
• Events written to tenant-scoped Kafka topics
• Webhook registration tracks events received and last event timestamp