Guides

Using Event Webhooks

Events allow you to be alerted when certain events occur in OneSchema's processing pipeline.

Suggest Edits

📘

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 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

Event TypeDescriptionAdditional MetadataNotes
embed_initializedOccurs when an embed session is first initialized.
embed_resumedOccurs when a previously closed embed session is resumed or when the SDK is initialized with a token after creating an embed via external API.
embed_closedOccurs when an embed session is closed.We only track these events when the importer is closed, and not on tab/window close
file_uploadedOccurs when a file is uploaded.
header_selectedOccurs when the header rows have been selected.
columns_mappedOccurs when columns are mappedvalidation_error_counts: Counts of errors grouped by validation error and column key.Error codes from validation webhooks can be inaccurate if the validation hooks have not completed before the embed is submitted or closed.
sheet_operation_performedOccurs when an operation takes place that affects the data on the Review & Finalize pane.operation: The type of operation performed.
import_submittedOccurs when the import is submittedimport_type: The method the embed was imported.

Trigger Types

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

Trigger TypeDescription
userThe event was initiated by a user in a OneSchema embed UI
apiThe event was initiated by an API call
automationThe event was initiated by an automation set in the customization

Example Payload

{
    "uuid": "event-34cbc6e7-7f94-4a9a-8f26-e5bfbee90f18",
    "embed_id": 53511,
    "embed_jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIxYTQxNWE5Ni0wOGE0LTRjYzUtOTcwZC0zOWM5YTQ1Mzc4MWEiLCJ1c2VyX2lkIjoiPFVTRVJfSUQ-In0.dvqE3c18PIk0Of3HWVES0SArXUhYvl8h8ua9bmhQ_t0",
    "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 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.

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.

Updated 4 months ago