Events Webhook

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

Events Webhook

All you need is a webhook URL and a name to create an Events webhook in OneSchema's product.

OneSchema currently sends events for the following events:

  • initial-validation-complete
  • import-complete
  • import-failed
  • sheet-deleted

Creating an Events webhook

Events webhooks can be created in the Developer Dashboard in the top left of the page header. Select the Webhooks tab in the left sidebar. Here you will see the Importer and Events Webhooks that have already been created in the system. Clicking the "Add a webhook" button will open up a modal with a form that will give you the options for creating a new webhook.

Every Webhook has a corresponding unique Webhook Key that will be used to refer to this particular Webhook in APIs that refer to Webhooks. The Webhook Key will default to a slugified version of the Webhook name. 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.

Receiving Events Data via Webhook

When an event occurs, OneSchema will send a POST request to the configured URL. The body of the request will be a JSON object with an event_type key indicating the type of the event. Additional fields depend on the event.

The initial-validation-complete event

The initial-validation-complete event is sent once validation, including any asynchronous validation hooks, is complete. It is only fired once, after a Template is applied to a Sheet. It is only fired when the Template is applied via an API request.

ParameterTypeDescription
sheet_id*IntegerThe id of the Sheet that was sent to the Import webhook
sheet_metadataObjectA JSON Object containing any custom metadata associated with the Sheet at time of import. Includes two additional fields added automatically by OneSchema: original_file_name containing the name of the original uploaded file, and original_sheet_name containing the name of the sheet in the imported Excel file, if part of a multi-sheet Excel file upload.
workspace_id*IntegerThe id of Workspace containing the Sheet.
workspace_metadataObjectA JSON Object containing any custom metadata associated with the Workspace.
template_key*StringThe key of the Template that was applied to the Sheet
status.num_rows*IntegerThe number of rows on the Sheet
status.num_rows_with_errors*IntegerThe number of rows on the Sheet with errors

The import-completed event

When a processed Sheet is sent to an Import Webhook, this event will be fired once all the batched requests have been sent.

ParameterTypeDescription
import_event_id*StringThe same event_id that was passed with each request to your import webhook.
sheet_id*IntegerThe id of the Sheet that was sent to the Import webhook
sheet_metadataObjectA JSON Object containing any custom metadata associated with the Sheet at time of import. Includes two additional fields added automatically by OneSchema: original_file_name containing the name of the original uploaded file, and original_sheet_name containing the name of the sheet in the imported Excel file, if part of a multi-sheet Excel file upload.
workspace_id*IntegerThe id of Workspace containing the Sheet.
workspace_metadataObjectA JSON Object containing any custom metadata associated with the Workspace.
template_key*StringThe key of the Template that was applied to the Sheet
responses[]*StringThe body of the responses returned by each batch request to the Import webhook

The import-failed event

When a processed Sheet is sent to an Import Webhook, this event will be fired if any errors occur.

ParameterTypeDescription
import_event_id*StringThe same event_id that was passed with each request to your import webhook.
sheet_id*IntegerThe id of the Sheet that was sent to the Import webhook
sheet_metadataObjectA JSON Object containing any custom metadata associated with the Sheet at time of import. Includes two additional fields added automatically by OneSchema: original_file_name containing the name of the original uploaded file, and original_sheet_name containing the name of the sheet in the imported Excel file, if part of a multi-sheet Excel file upload.
workspace_id*IntegerThe id of Workspace containing the Sheet.
workspace_metadataObjectA JSON Object containing any custom metadata associated with the Workspace.
template_key*StringThe key of the Template that was applied to the Sheet
error_data.error*StringAn error code explaining what went wrong
error_data.bodyStringIf a request to your Import webhook failed, the body of the response received from your serve

The sheet-deleted event

This event is fired when a sheet is deleted.

ParameterTypeDescription
sheet_id*IntegerThe id of the Sheet that was deleted