Skip to main content

Webhook

Overview​

The Webhook source allows you to push data directly to Saddle Data from any external system or service. This is ideal for real-time ingestion, event-driven data, and integrations with services that support outbound webhooks.

Configuration​

When creating a Webhook Connection, Saddle Data automatically generates:

  • Webhook ID: A unique public identifier for your endpoint.
  • Webhook Secret: A secure key used to authenticate requests.

These details are displayed once upon creation and can be viewed later in the Connection settings.

Endpoint URL​

The URL for your webhook will follow this pattern: https://hooks.saddledata.io/v1/hooks/<WEBHOOK_ID>

Authentication​

Authentication is required for all requests to the webhook endpoint. You can authenticate in two ways:

  1. Header: Include the secret in the X-Saddle-Secret header.
  2. Query Parameter: Append the secret to the URL as a query parameter: ?secret=<WEBHOOK_SECRET>

Payload Format​

The Webhook source supports any valid JSON payload.

Single Object​

You can post a single JSON object representing one record:

{
  "id": 123,
  "event": "user_signup",
  "email": "[email protected]"
}

Batch Processing (JSON Array)​

Saddle Data supports high-throughput batching. You can post an array of JSON objects, and each item will be processed as an individual record:

[
  { "id": 1, "status": "active" },
  { "id": 2, "status": "pending" }
]

Data Processing​

Unlike typical polling sources, Webhook data is ingested instantly into a high-performance buffer. A background process then syncs this buffered data to your destination.

Sync Frequency: The frequency of this sync operation is managed automatically by Saddle Data based on your Subscription Plan.

  • Starter Plan: Syncs every 5 minutes.
  • Pro/Enterprise: Supports faster sync intervals (e.g., 1 minute).

You do not need to configure a cron schedule for Webhook flows; the system auto-configures the optimal schedule.

Schema & Mapping​

When configuring a flow with a Webhook source, you will be asked to provide a JSON Sample. Saddle Data uses this sample to:

  1. Infer the schema (field names and types).
  2. Add metadata fields (e.g., _event_id, _received_at, _headers).
  3. Allow you to map these fields to your destination columns.

Metadata Fields​

Saddle Data automatically enriches every webhook record with the following metadata:

  • _event_id: A unique ID assigned by Redis Streams.
  • _received_at: The timestamp when the webhook was received.
  • _headers: A JSON object containing the HTTP headers from the request.

Sync Modes​

Webhooks are push-based and typically use the following sync patterns at the destination:

  • Incremental - Append: Best for immutable event streams.
  • Incremental - Deduped (Upsert): Best for state updates, where you use a field like id from your JSON as the Primary Key.

Declarative Configuration​

apiVersion: v1
kind: Connection
metadata:
  name: webhook-connection
spec:
  connectorId: webhook
  configuration:
    secret: '********'
    webhook_id: my-webhook-id
    capability: source