Incoming Webhooks

Incoming webhooks enable you to receive and act on data sent from 3rd party platforms. 

For example: 

• Every time a customer is updated in Stripe, update Tadabase. 
• When a new form is received from JotForm, update Tadabase

While you might already be doing this with 3rd party software like Zapier or Integromat, our incoming webhook catcher is purpose-built for your Tadabase app, and is better at working with larger and more rapid requests. 

Getting Started

Getting started is fairly straightforward: 

1. Create an account
2. Add your Apps
3. Create Webhooks

Create Account

To get started, go to https://catch.tadabase.io and log in/create your account. When creating an account, make sure you use the same email as your Tadabase account. Feel free to use any password you wish. 

Our Webhook Catcher is intentionally built separately from our Builder as a microservice. This means you'll need to create a new account. We are providing this as a microservice to ensure it can be iterated and updated more frequently, as well as being able to scale more rapidly.

Add your Apps

Once you've logged in, add all the apps you wish to create incoming webhooks for. Simply give the app a name, description, and the API credentials from within your Tadabase app.

Create Webhooks

To create a webhook, give your webhook a name and description for your reference. Then select the app to be used for this webhook. 

When saving data to your app, the webhook enables you to determine how equations should be run. 

The options are: 

• Run Equations
• Send Equations to the Queue
• Don't run Equations 

When you run equations, each request will take a bit of extra time as the data is processed. However, there are times when you want the record to get added more quickly. In that case, you can choose to send equations to the queue or not run equations at all. 

When choose to not run equations, any equation in your Tadabase App will not be updated until you manually trigger them. You can do this by running a special API call.

Once you've completed the necessary webhook information, a new endpoint URL will be dynamically created for you. Copy this and use this in whichever external service you want to send webhooks from. 

In this example, we'll look at a sample Stripe request. We want to save all changes made in Stripe Customers directly back to our app. 

Inside of Stripe go to Developers -> Webhooks and click on +Add endpoint: 

Paste in the generated Webhook endpoint URL and choose which events should receive this webhook. For this example, we'll choose Customer Created.

Now let's create a new test customer.

Back in the webhook catcher, refresh the page and you'll be able to see the request from Stripe. Our next step is to map the request from Stripe to the Data Table and Fields within our app. 

• Choose Data Table
• Choose to update or create new records
• Determine if this webhook has multiple values/records
• Map fields

Field Mapping

Field mapping is the process of connecting data from incoming webhooks to specific fields in your Tadabase app. It's like matching pieces of a puzzle – each piece of data from an external source needs a designated spot in your app. Here's how it works in a nutshell:

Choose the Data Table

Think of a Data Table as a digital file cabinet inside your app. You need to decide which cabinet (Data Table) the incoming data should go into.

Update or Create

Decide if the incoming data will create a new record or update an existing one. Creating a new record is like adding a new file to the cabinet, while updating is like editing an existing file.

• For Creating a New Record: Simply provide the details, and a new file (record) will be created in your cabinet.
• For Updating an Existing Record: You need to specify which file (record) in the cabinet should be updated. If the incoming data has an ID, match it with the ID in your app. If not, you can create a new file or update an existing one based on your choice.

When Updating an Existing Record, you'll need to put in the ID of the record that should be updated. If the incoming request contains the ID, put in the key name for that value. If it's a static value, choose Static and enter the static record ID to be updated. 

Map Fields

Imagine each field in your Data Table as a labeled drawer in your file cabinet. You need to tell the system where to put each piece of incoming data.

For example, if the incoming data has a key called "name" and you want this to go into the "Name" drawer in your app, you would simply copy the key text and paste it into the destination field.

{
  "name" : "John Doe"
}

Incoming Data Key: name
Destination Field: Name

If the incoming data is organized in a nested manner (like a box inside a box), you need to provide the full path to the data. For instance, if "name" is inside an "object," which is inside a "data" box, you specify it as:

{
  "data" : {
    "object" : {
      "name" : "John Doe"
    }
  }
}
          	
Incoming Data Key: data.object.name
Destination Field: Name

Nested Arrays

When dealing with arrays, indicated with [] brackets instead of {} brackets, it's like working with a set of Russian dolls – you have boxes within boxes. Let's break down how to map values from nested arrays using your example:

{
  "event_id": "01HE5T1TEF73VCE2YNCXJ17MPY",
  "event_type": "form_response",
  "form_response": {
    "form_id": "XYZ456",
    "landed_at": "2023-11-01T16:04:08Z",
    "submitted_at": "2023-11-01T16:04:20Z",
    "hidden": {
      "rel_survey_id": "ABC123"
    },
    "definition": {
      "id": "XYZ456",
      "title": "My typeform",
      "fields": [{
        "id": "000AAA000",
        "ref": "01HE5P596JYV5CMPW29VEESRBX",
        "type": "short_text",
        "title": "Hello, what's your name?",
        "properties": []
      }]
    }
  }
}

In this JSON, the value "Hello, what's your name?" is nested within arrays and objects. To map this value correctly, you need to navigate through the structure:

1. Identify the Array Index:

   • The "fields" array contains multiple objects.
   • To access the first object in the array, use index 0 like this: form_response.definition.fields.0

2. Map the Value:

   • "form_response" is the main object.
   • Inside it, go to "definition".
   • Inside "definition", navigate to the "fields" array.
   • Use the index 0 to access the first object.
   • Finally, map the "title" key: form_response.definition.fields.0.title

By mapping it this way, you're specifying the exact path to the value you want to extract from the nested array. Remember, the index (0 in this case) is crucial to pinpoint the right item within the array. This approach ensures that you accurately capture the desired information from the complex, nested structure of your JSON data.

Static Values vs. Dynamic Values vs. Conditional Values

• Dynamic Value: It changes with every incoming request, adapting to different data each time.
• Static Value: It remains the same for every request, like a fixed label on a file.
• Special Option - save the Webhook ID or Webhook Call ID to your app.

Conditional Values

• Conditional Fields: You can now add conditional rules to fields. This means you can specify different conditions for processing data based on the incoming values. For example, if a field value matches a specific condition, the webhook will perform an action based on that condition.

• "Match Any" Condition: In addition to regular conditions, we’ve added a “Match Any” option, which allows the webhook to trigger an action if any one of the specified conditions is met.

• Default Values for Conditions: If no conditions are met, you can now set a default value for the field, ensuring smooth data processing.

And that's it! Field mapping ensures that the right information finds its way into the correct places within your app, making sure your digital filing system stays organized and up-to-date.

Multi-Value Webhooks

You can break an incoming request into multiple records. For example, suppose your incoming payload looks like this: 

{
      "customers": [{
            "name": "John",
            "email": "john@tadabase.io",
            "country": "USA"
      }, {
            "name": "John 2",
            "email": "john2@tadabase.io",
            "country": "USA"
      }]
}

Here the "Array Key" will be "customers", each record inside that array can be its own record. 

If you are using a multi-value array, you can not access any values outside of the array. For example, in the payload below, the "date" is not available because it lives outside of the customers array. 

{
      "date": "2021-10-15",
      "customers": [{
            "name": "John",
            "email": "john@tadabase.io",
            "country": "USA"
      }, {
            "name": "John 2",
            "email": "john2@tadabase.io",
            "country": "USA"
      }]
}

Once you add the array key into the Multi-value field, any values inside the array can be access directly in the other fields. 

The above request will result in 2 records being added: