Source Adapters

Source adapters let external systems push data into Mixpeek buckets via webhooks. When an event fires in your upstream platform (a video finishes encoding, an asset is published, a record is created), the platform sends a webhook to Mixpeek, which automatically creates a bucket object with the right metadata and file references. This is the push-based complement to syncs, which poll external systems on a schedule.

How It Works

Your Platform → webhook POST → Mixpeek Source Adapter → Bucket Object → Batch Processing

You configure a source adapter on a bucket via PATCH /v1/buckets/{bucket_id}
Mixpeek returns a webhook_secret and an ingest URL
You point your platform’s webhook settings at the ingest URL
When events arrive, the adapter verifies the signature, extracts metadata, resolves the file URL, and creates an object
Depending on the batching mode, objects are processed immediately or buffered for batch submission

Supported Adapter Types

Adapter	Use Case
`mux`	Video assets from Mux — listens for `video.asset.ready` events, resolves playback URLs and metadata
`supabase`	Database rows from Supabase — listens for `INSERT`/`UPDATE` webhooks, supports writeback of results via PostgREST
`generic_webhook`	Any system that sends JSON webhooks — you configure dot-path extraction for ID, file URL, and metadata fields

Configuration Reference

Source adapters use the same org-level connections as syncs. Create a connection once, then reference it from any number of adapters or syncs.

Create a connection (once per provider account)

curl -sS -X POST "$MP_API_URL/v1/organizations/connections" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-video-platform",
    "provider_type": "mux",
    "provider_config": {
      "access_token_id": "YOUR_TOKEN_ID",
      "access_token_secret": "YOUR_TOKEN_SECRET"
    }
  }'

Save the returned connection_id (e.g., conn_abc123).

Configure the source adapter on a bucket

curl -sS -X PATCH "$MP_API_URL/v1/buckets/$BUCKET_ID" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "X-Namespace: $MP_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "source_adapter": {
      "adapter_type": "mux",
      "connection_id": "conn_abc123",
      "event_filter": {
        "event_types": ["video.asset.ready"]
      },
      "field_mapping": {
        "duration": "duration",
        "resolution_tier": "resolution"
      },
      "blob_source": {
        "file_field": "playback_url",
        "blob_type": "video",
        "target_property": "video"
      },
      "batching": {
        "mode": "immediate"
      },
      "dedup_key": "data.id"
    }
  }'

Credentials are encrypted at rest in the connection and resolved only when a webhook arrives. The same connection can be shared across multiple buckets and syncs. The response includes the generated webhook_secret and the ingest URL:

{
  "bucket_id": "bkt_abc123",
  "source_adapter": {
    "adapter_type": "generic_webhook",
    "enabled": true,
    "webhook_secret": "a1b2c3d4e5f6...",
    ...
  }
}

Your ingest endpoint is:

POST /v1/buckets/{bucket_id}/source-adapter/ingest

Fields

Field	Required	Default	Description
`adapter_type`	Yes	—	`mux`, `supabase`, or `generic_webhook`
`enabled`	No	`true`	Enable or disable the adapter without removing configuration
`connection_id`	Recommended	—	Reference to an org-level connection (`conn_...`). Credentials are encrypted at rest and resolved at runtime. See Connections.
`connection.credentials`	Fallback	`{}`	Inline credentials for simple setups. Use `connection_id` instead for production — inline credentials are stored unencrypted.
`event_filter.event_types`	No	Adapter default	Array of event type strings to process. Unmatched events return `handled: false`
`field_mapping`	No	`{}`	Map of dot-paths in the external payload to bucket schema field names
`blob_source.file_field`	No	—	Dot-path to the downloadable file URL in the adapter result metadata
`blob_source.blob_type`	No	`video`	Blob type: `video`, `image`, `audio`, `text`, `json`
`blob_source.target_property`	No	—	Bucket schema property name where the blob is stored
`batching.mode`	No	`time_window`	`immediate`, `time_window`, or `count` (see Batching)
`batching.window_seconds`	No	`30`	Buffer window for `time_window` mode (5–300 seconds)
`batching.max_batch_size`	No	`100`	Max events per batch (1–1000)
`batching.auto_submit`	No	`true`	Automatically submit batch for processing after flush
`dedup_key`	No	—	Dot-path in the payload used to extract a unique ID for deduplication

Field Mapping

Field mapping translates external metadata into your bucket schema. Keys are dot-paths into the external payload or adapter result; values are your bucket schema field names.

{
  "field_mapping": {
    "duration": "video_duration",
    "resolution_tier": "resolution",
    "passthrough": "external_metadata",
    "thumbnail_url": "thumbnail"
  }
}

Dot-paths support nested access (data.nested.field) and are evaluated against the metadata returned by the adapter after it fetches or extracts asset information.

Batching

Source adapters support three batching modes:

Mode	Behavior
`immediate`	Each event creates an object and optionally triggers processing inline. Lowest latency.
`time_window`	Events buffer for `window_seconds`, then flush as a batch. Efficient for bursty sources.
`count`	Events buffer until `max_batch_size` is reached, then flush. Predictable batch sizes.

For time_window and count modes, a background worker flushes buffered events periodically. When auto_submit is true, the flushed objects are automatically submitted as a batch for processing.

Deduplication

Set dedup_key to a dot-path that uniquely identifies events (e.g., data.id for the external asset ID). The adapter tracks processed events and returns status: "duplicate" for repeated deliveries instead of creating duplicate objects.

{
  "dedup_key": "data.id"
}

This is important for webhook reliability — external systems often retry deliveries, and dedup prevents duplicate objects.

Writeback

Some source adapters support writeback — pushing processing results back to the source system after an alert fires or a batch completes. This closes the loop so the source system stays the single source of truth. Writeback is configured in the writeback key inside source_adapter:

{
  "writeback": {
    "enabled": true,
    "trigger": "on_alert",
    "external_id_field": "listing_url",
    "field_mapping": [
      { "source_path": "verdict_classification", "target_field": "mp_verdict" },
      { "source_path": "verdict_confidence", "target_field": "mp_confidence" }
    ]
  }
}

Adapter	Writeback method
`supabase`	PostgREST `PATCH` to the source table
`generic_webhook`	HTTP `POST` to a `writeback_url`
`mux`	Not supported

See the Writeback reference for full configuration details, trigger types, and examples.

Signature Verification

Every source adapter verifies inbound requests to prevent unauthorized event injection:

Provider-specific adapters (Mux) verify using the provider’s native HMAC signature scheme (e.g., Mux-Signature header)
All adapters support a fallback X-Webhook-Secret header check against the webhook_secret returned when you configured the adapter
Requests with invalid or missing signatures return 401 Unauthorized

Store your webhook secret securely. The webhook_secret is returned once when you configure the adapter. Treat it like an API key. If you lose it, reconfigure the adapter to generate a new one.

Monitoring

Check adapter status and event statistics:

curl -sS "$MP_API_URL/v1/buckets/$BUCKET_ID/source-adapter/status" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "X-Namespace: $MP_NAMESPACE"

Response:

{
  "enabled": true,
  "adapter_type": "mux",
  "events_buffered": 0,
  "events_processed_24h": 42,
  "events_failed_24h": 1,
  "last_flush_at": "2026-01-15T10:03:22Z",
  "last_error": null,
  "webhook_url": null
}

Example: Mux Video Ingestion

Configure a bucket to automatically ingest Mux videos as they finish encoding:

Create a bucket with a video schema

curl -sS -X POST "$MP_API_URL/v1/buckets" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "X-Namespace: $MP_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket_name": "mux-videos",
    "bucket_schema": {
      "properties": {
        "video": { "type": "video" },
        "duration": { "type": "float" },
        "resolution": { "type": "string" },
        "thumbnail_url": { "type": "string" }
      }
    }
  }'

Create a Mux connection

curl -sS -X POST "$MP_API_URL/v1/organizations/connections" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mux-production",
    "provider_type": "mux",
    "provider_config": {
      "access_token_id": "YOUR_MUX_TOKEN_ID",
      "access_token_secret": "YOUR_MUX_TOKEN_SECRET"
    }
  }'

Save the returned connection_id.

Configure the Mux source adapter

curl -sS -X PATCH "$MP_API_URL/v1/buckets/$BUCKET_ID" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "X-Namespace: $MP_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "source_adapter": {
      "adapter_type": "mux",
      "connection_id": "conn_YOUR_CONNECTION_ID",
      "event_filter": {
        "event_types": ["video.asset.ready"]
      },
      "field_mapping": {
        "duration": "duration",
        "resolution_tier": "resolution",
        "thumbnail_url": "thumbnail_url"
      },
      "blob_source": {
        "file_field": "playback_url",
        "blob_type": "video",
        "target_property": "video"
      },
      "batching": { "mode": "immediate" },
      "dedup_key": "data.id"
    }
  }'

Save the webhook_secret from the response.

Point Mux webhooks at the ingest URL

In the Mux Dashboard under Settings > Webhooks, add a new webhook:

URL: https://api.mixpeek.com/v1/buckets/{bucket_id}/source-adapter/ingest
Events: video.asset.ready

If using the X-Webhook-Secret header for verification, configure your webhook sender to include it.

Verify

Upload a video to Mux. Once encoding completes, the video.asset.ready event fires, and a new object appears in your bucket with metadata (duration, resolution, thumbnail) and the video blob ready for processing.Check the adapter status endpoint to confirm events are flowing.

Syncs vs Source Adapters

Aspect	Syncs	Source Adapters
Direction	Mixpeek polls the external system	External system pushes to Mixpeek
Latency	Polling interval (seconds to minutes)	Near-real-time (event-driven)
Setup	Configure credentials + schedule	Configure credentials + point webhooks
Best for	Bulk imports, systems without webhooks	Real-time ingestion, event-driven workflows

You can use both on the same bucket — syncs for initial backfill, source adapters for ongoing real-time ingestion.

Buckets — bucket creation and schema design
Object Storage Syncs — pull-based ingestion
Webhooks — outbound event notifications from Mixpeek
Batch Processing — processing objects after ingestion

Integrations

Documentation Index

​How It Works

​Supported Adapter Types

​Configuration Reference

​Fields

​Field Mapping

​Batching

​Deduplication

​Writeback

​Signature Verification

​Monitoring

​Example: Mux Video Ingestion

​Syncs vs Source Adapters

​Related

How It Works

Supported Adapter Types

Configuration Reference

Fields

Field Mapping

Batching

Deduplication

Writeback

Signature Verification

Monitoring

Example: Mux Video Ingestion

Syncs vs Source Adapters

Related