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. The User-Agent HTTP header is set to OneSchema/1.0.

Creating a webhook

To access the webhook creation menu, first go to the Dashboard in the top left 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 "Create a new 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

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

Example JSON POST

{
  "request_id": "req_i64b5857b-2b56-40d1-b9d5-0ca64da84495",
  "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,
  "total_record_count": 141,
  "data": {
    "count": 50,
    "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). List of all available validations, and their corresponding error codes available here.

Retries

If the webhook call times out after 30 seconds, or if the webhook returns a server error response code (5xx), OneSchema will retry the the call up to three times with exponential backoff.

A 408 (request timeout) or 429 (too many requests) code will also prompt OneSchema to retry.

The request_id will be the same for every retry.