Events

OneSchema uses events to let you know about your customers’ interactions inside a OneSchema importer. Examples of potential use cases for event webhooks include:

• Advanced analytics: piping events to your analytics platform to perform more complex analysis.
• Monitoring and alerting: creating alerts and monitoring if your customers are getting stuck in the OneSchema importer.
• Auditability: logging the operations in a OneSchema session for compliance requirements.

Events Model

Event Types

Trigger Types

The trigger type determines how the event was initiated. The supported trigger sources are:

Example Payload

{
    "id": 1234,
    "uuid": "event-34cbc6e7-7f94-4a9a-8f26-e5bfbee90f18",
    "embed_id": 53511,
    "embed_jwt": "<EMBED_JWT>",
    "environment_name": "Production",
    "template_key": "contacts",
    "event_type": "embed_initialized",
    "trigger_type": "user",
    "data": {},
    "created_at": 1706112805.512352
}

Receiving Events via Webhook

Creating an Event Webhook

An event webhook can be created in the Developer Dashboard in the Webhooks tab. During configuration, select the types of events that the webhook will be subscribed to. Environment variables can be set in the url of the event webhook.

Every webhook has a corresponding unique key property that will be used to identify the webhook in relevant APIs; it can be changed later.

To secure your webhook, we can optionally authenticate webhook requests using HTTP Basic Auth. If a secret key is supplied, the secret key will be used as the basic auth password. No username is passed through.

Assign an Event Webhook to an Embed

To use event webhooks, they must be assigned during the initialization of an embed. This applies whether embed initialization occurs via an Importer SDK or API.

For either approach, specify the relevant event webhooks that should be subscribed for the resulting embed. The webhooks should be specified in the eventWebhookKeys parameter as a list, and each webhook should be identified by the key property.

<OneSchemaImporter
  clientId="25ec3a35-eccf-4b68-859b-7796bb9be4ba"
  ...
  eventWebhookKeys={["event_webhook"]}
/>

const importer = oneschemaImporter({
  clientId: "67bb2e5f-f0f7-42a6-a511-18b25e67b8c4",
  ...
  eventWebhookKeys: ["event_webhook"],
})

Detailed information on usage of the eventWebhookKeys property can be found in SDK and API documentation.

📘

Attaching metadata to an event

The event webhook includes the embed JWT passed to the embed. The JWT is the recommended way to pass any metadata such as analytics identifiers, performance trace IDs, or anything else you might find useful when processing the event.

Receiving Data via Webhook

When a registered event occurs for an embed, OneSchema will send a POST request to all webhooks associated with the event and embed. The webhook endpoint should respond promptly with a 2xx response.

OneSchema will retry the webhook call up to two times if the request timed out or the server responded with a 408 (request timeout) or 429 (too many requests) code.

Developers should handle retries gracefully and leverage the UUID to prevent duplicate processing of events.

Multi FileFeed Event Webhooks

For Multi FileFeed imports, event webhooks are the recommended primary way to monitor import status. A webhook fires as soon as an import reaches a terminal state, so you do not need to poll at high frequency. Some imports (for example, imports that are never submitted, or stuck imports that are cleaned up automatically) do not produce a webhook, so for critical pipelines we recommend supplementing webhooks with low-frequency reconciliation polling. See Running in production — Limitations for details.

Setting up MFF event webhooks

1. In the OneSchema dashboard, go to Developer → Webhooks.
2. Open the Multi FileFeeds tab.
3. Create an event webhook. Give it a key, endpoint URL, optional secret, and subscribe to the events you need:
   • multi_file_feed_import_success
   • multi_file_feed_import_error
4. Attach the webhook to each MFF that should use it:
   • In the dashboard, open the MFF's settings, find the Event Webhook section, and select the webhook you created.
   • When creating or updating a MFF through the API, set multi_filefeed_event_webhook_key to the webhook's key.

MFF event webhooks are created at the organization level, but each MFF must be associated with a webhook before deliveries are sent.

You can also create and manage webhooks through the Event Webhooks API. Use product_area: multi_file_feeds when creating a webhook for MFF imports.

Import events

Payload

{
  "request_id": "req_wfevt_<uuid>",
  "event_type": "multi_file_feed_import_success",
  "multi_file_feed_id": 123,
  "multi_file_feed_name": "My MFF",
  "multi_file_feed_metadata": {},
  "created_at": "2026-06-15T21:00:00.000Z",
  "multi_file_feed_import_id": 456,
  "uploaded_file_names": ["transactions_june.csv"]
}

The error event adds an error_type field with one of: Runtime Error, Transforms Error, Validations Error, or Interrupted. The payload does not include the full error message — use the Get import errors endpoint to retrieve details.

For the full payload reference, delivery semantics, and known limitations, see Running in production — Event webhooks.

Matching webhooks to your uploads

When you create an import through the API, save the returned id. That value is the multi_file_feed_import_id you will receive in the webhook, and it is the authoritative key for matching a webhook to the original import. The uploaded_file_names field can help confirm which files the event belongs to, but use it only as supplemental metadata — file names are not guaranteed to be unique across imports (or even within a single import). Store request_id to deduplicate any duplicate deliveries.

Fallback polling

If you cannot receive webhooks, or for critical pipelines, poll the Get import endpoint as a fallback. Poll only while an import is still in progress, use exponential backoff, and do not poll more than once every few seconds. For most imports, polling once every 5–10 seconds is sufficient. Stop polling once the import reaches a terminal state.

For cases where no webhook is sent, periodic reconciliation polling (for example, every few minutes) can catch stuck or never-submitted imports. See Running in production — Limitations.

Fetch Events via API

Another way to get events is to use the GET embed events API.

Note that events are automatically deleted per your org's data retention policy.