📘
Please contact your OneSchema representative for more info on getting access to event webhooks

Events

OneSchema uses events to let you know about your customers’ interactions during a OneSchema FileFeed run.

Base Payload

All FileFeed Event Webhooks share the same base payload. The Additional Metadata column in the following section defines the fields that will appear for the specific FileFeed event type.

{
  "request_id": "req_f9b8d73df-7fd3-4243-9b9a-f5ca899daa32",
  "event_type": "file_feed_event_type",
  "file_feed_id": 121175,
  "file_feed_name": "file_feed_name",
  "file_feed_metadata": {
    "foo": "bar"
  },
  "created_at": "2025-02-21T19:52:11.878Z",
}

Events Model

Event Types

Event Type	Description	Additional Metadata
file_feed_import_success	A successful FileFeed import.	`file_feed_import_id` `environment_name` `last_import_attempt` `embed_user_jwt`
file_feed_import_error	A FileFeed error.	`file_feed_import_id` `environment_name` `last_import_attempt` `embed_user_jwt`
file_feed_import_partial	A partial FileFeed import.	`file_feed_import_id` `environment_name` `last_import_attempt` `embed_user_jwt`
file_feed_ingestion_success	Successful ingestion event occurred. Currently, this is only configured for `sftp`. Any time a successful `sftp` pull occurs, this will fire.	`sftp_host` `sftp_path` `ingested_files_count`
file_feed_ingestion_error	Error occurred during ingestion. Currently, this is only configured for `sftp`. If an `sftp` pull is requested, and an error occurs that precludes successful file retrieval, this will fire.	`sftp_host` `sftp_path` `error_message`

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.

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

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. The webhook endpoint should respond promptly with a 200 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.