Importer Webhook

Importer webhooks allow you to process data from OneSchema and insert data directly into your database.

Importer Webhook

All you need is a webhook URL and a name to create a webhook in OneSchema's product. Once the webhook is created, a Webhook Export option will be available for all subsequent exports that will send a POST request with JSON to the webhook URL endpoint.

Creating a webhook

To access the webhook creation menu, first go to the Developer Dashboard in the top right of the page header. Then, select the Webhooks tab in the left sidebar. You will see a list of the 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 Data via Webhook

When exporting data via a webhook, OneSchema’s servers will POST JSON data to the endpoint provided. Larger lists may require multiple requests to send all of the rows in the list.

The payload of each request will be a JSON object with the following metadata fields:

Schema of Webhook Payload Metadata

ParameterTypeDescription
event_id*StringUnique id generated for the export. Used to combine data from multiple requests when exporting larger lists.
webhook_key*StringThe Webhook Key for the webhook used for the export.
template_key*StringThe Template Key for the Template applied to the list at the time of export.
workspace_id*IntegerThe id of Workspace the exported Sheet belongs to.
workspace_metadataObjectA JSON Object containing any custom metadata associated with the Workspace.
sheet_id*IntegerThe id of the Sheet being exported
sheet_metadata*ObjectA 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.
columns*ArrayInformation about the columns that are included in the export.
embed_user_jwt*StringWhen exporting data that was imported from an embedded OneSchema instance, the user JWT that was used to initiate the embedded import flow.
sequence_number*IntegerCurrent request for the current export, numbered 1 through sequence_count.
sequence_count*IntegerNumber of requests that will be made for this webhook export.

Actual row data will be nested inside the data attribute of the request payload. Rows without errors will be represented as JSON Objects in a records field. The keys of these objects will be the Column Keys of the Template’s columns. Data in unmapped columns will not be returned.

Data for rows with errors will be returned in the error_records field. Each element in this array will be a JSON Object with two fields. The data field will contain the actual row data (in the same format as the Objects in the records field). The errors field will be an Object where the keys are Column Keys and the values are error codes.

Schema of Webhook Payload Row Data

ParameterTypeDescription
data.countIntegerNumber of records contained in the request, default of 1000, configurable via the UI.
data.recordsObject[]Array of records that have no errors
data.error_recordsObject[]Array of records that have one or more errors
data.error_records.dataObjectThe original data for a record that contains errors
data.error_records.errorsObjectErrors for a record that contains errors. The keys of the object are the columns with errors, and the values are lists of error codes

Example JSON POST

{
  "event_id": "123e4567-e89b-12d3-a456-426614174000",
  "webhook_key": "webook-123",
  "template_key": "contact-template",
  "webhook_id": 209,
  "sheet_id": 123,
  "sheet_metadata": {
    "original_file_name": "contacts.csv"
  },
  "columns": [
    {
      "sheet_column_name": "First Name",
      "template_column_name": "First Name",
      "template_column_key": "first_name"
    },
    {
      "sheet_column_name": "Last Name",
      "template_column_name": "Last Name",
      "template_column_key": "last_name"
    },
    {
      "sheet_column_name": "Email",
      "template_column_name": "Email",
      "template_column_key": "email"
    },
    {
      "sheet_column_name": "Account Name",
      "template_column_name": "Account Name",
      "template_column_key": "account_name"
    },
    {
      "sheet_column_name": "Market Segment",
      "template_column_name": "Market Segment",
      "template_column_key": "market_segment"
    }
  ],
  "embed_user_jwt": "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI2N2JiMmU1Zi1mMGY3LTQyYTYtYTUxMS0xOGIyNWU2N2I4YzQiLCJ1c2VyX2asdasdasdasd.MaxfODdhWqVamNgK7l8mZrR-A4B2uGDuPWLOreu7dQI",
  "sequence_number": 1,
  "sequence_count": 3,
  "data": {
    "count": 262,
    "records": [
      {
        "first_name": "Aditi",
        "last_name": "Goel",
        "email": "[email protected]",
        "account_name": "Google",
        "market_segment": "ENT"
      },
      {
        "first_name": "Laura",
        "last_name": "Quinn",
        "email": "[email protected]",
        "account_name": "Airbnb",
        "market_segment": "MM"
      },
      {
        "first_name": "Aditi",
        "last_name": "Goel",
        "email": "[email protected]",
        "account_name": "Google",
        "market_segment": "ENT"
      },
      {
        "first_name": "Nancy",
        "last_name": "Zuo",
        "email": "[email protected]",
        "account_name": "Gigashots",
        "market_segment": "MM"
      },
      {
        "first_name": "Liam",
        "last_name": "Quipp",
        "email": "[email protected]",
        "account_name": "Box",
        "market_segment": "SMB"
      },
      {
        "first_name": "Lexie",
        "last_name": "Goodrick",
        "email": "[email protected]",
        "account_name": "Roblox",
        "market_segment": "ENT"
      }
    ],
    "error_records": [
      {
        "data": {
          "first_name": "Robert",
          "last_name": "",
          "email": "[email protected]",
          "account_name": "Datadog",
          "market_segment": "snb"
        },
        "errors": {
          "last_name": 23,
          "market_segment": 38
        }
      }
    ]
  }
}

Error Codes

Error codes will indicate the type of validation that failed (e.g., a MM/DD/YY date validation, or and email address validation). Here is a list of all available validations, and their corresponding error codes:

Must be from picklist: 1

Must be a number: 2
Must be a percentage: 40

Must match MM/DD/YYYY date format: 3
Must match DD/MM/YYYY date format: 25
Must match ISO 8601 date format: 29
Must match ISO 8601 datetime format: 30
Must match YYYY/MM/DD date format: 34
Must match DD/MMM/YYYY date format: 35
Must match HH:NN time format: 26
Must match MM/DD/YYYY HH:MM: 45
Must be a Unix timestamp: 46

Must be a URL: 8
Must be a internet domain: 10
Must be a file name with extension: 48
Must be a UUID: 52

Must be a full name: 9
Must be a first name: 11
Must be a last name: 12
Must be an email address: 13

Must be a unit of measure: 5
Must be a currency code: 6
Must be a phone number: 7
Must be a quantity of money: 31
Must be a IANA timezone: 33

Must match a custom regex: 36
Must be only letters: 37
Must be a valid CAS number: 41
Must match masked SSN format: 42
Must match unmasked SSN format: 43
Must be a US phone number with optional extension: 44

Must be a ZIP/Postal code: 23
Must be a US State or Territory: 50
Must be a Country: 51

Data is duplicate of previously seen data: 1000
Data is missing: 1001
Unable to enrich location data: 1002
Row validation error occurred: 1003
Data is shorter than min character limit: 1004
Data is longer than max character limit: 1005

Text should be in "Title Case": 2000
Text should be in "UPPER CASE": 2001
Text should be in "lower case": 2002

Text has surrounding whitespace: 2010

Validation webhook said this was an error: 3001
Validation webhook said this was a warning: 3002

Embedding

When using webhooks, the user JWT token used to initiate the embed flow will be included in the payload metadata under the key userJwt. After going through the embed flow, the user can import the cleaned data via the Webhook specified by the webhookKey. For more information, see the documentation for OneSchema Embedding.

JSON Export

If webhookKey is not specified, the imported data is included in the "success" event. The payload looks similar to the webhook export payload, except that some fields aren't included and the "count", "records", and "error_records" keys are top-level keys. This is an example payload:

{
  "columns": [
    {
      "sheet_column_name": "First Name",
      "template_column_name": "First Name",
      "template_column_key": "first_name"
    },
    {
      "sheet_column_name": "Last Name",
      "template_column_name": "Last Name",
      "template_column_key": "last_name"
    },
    {
      "sheet_column_name": "Email",
      "template_column_name": "Email",
      "template_column_key": "email"
    },
    {
      "sheet_column_name": "Account Name",
      "template_column_name": "Account Name",
      "template_column_key": "account_name",
    },
    {
      "sheet_column_name": "Market Segment",
      "template_column_name": "Market Segment",
      "template_column_key": "market_segment"
    }
  ],
  "count": 262,
  "records": [
    {
      "first_name": "Aditi",
      "last_name": "Goel",
      "email": "[email protected]",
      "account_name": "Google",
      "market_segment": "ENT"
    },
    {
      "first_name": "Laura",
      "last_name": "Quinn",
      "email": "[email protected]",
      "account_name": "Airbnb",
      "market_segment": "MM"
    },
    {
      "first_name": "Aditi",
      "last_name": "Goel",
      "email": "[email protected]",
      "account_name": "Google",
      "market_segment": "ENT"
    },
    {
      "first_name": "Nancy",
      "last_name": "Zuo",
      "email": "[email protected]",
      "account_name": "Gigashots",
      "market_segment": "MM"
    },
    {
      "first_name": "Liam",
      "last_name": "Quipp",
      "email": "[email protected]",
      "account_name": "Box",
      "market_segment": "SMB"
    },
    {
      "first_name": "Lexie",
      "last_name": "Goodrick",
      "email": "[email protected]",
      "account_name": "Roblox",
      "market_segment": "ENT"
    }
  ],
  "error_records": [
    {
      "data": {
        "first_name": "Robert",
        "last_name": "",
        "email": "[email protected]",
        "account_name": "Datadog",
        "market_segment": "snb"
      },
      "errors": {
        "last_name": 23,
        "market_segment": 38
      }
    }
  ],
}