Stitch Documentation
has moved!

Please update your bookmarks to

If you're not automatically redirected after 5 seconds, click here.

Stitch Webhooks FAQ

We’re currently doing some private testing on our Incoming Webhooks integration. Want to be a part of it? Get in touch with us.


What is the Stitch Incoming Webhooks integration?

Stitch’s Incoming Webhooks integration provides a simple and flexible method to integrate any existing webhook API with Stitch. If Stitch doesn’t have a native integration for the webhook you want to integrate, then Stitch webhooks is your best bet.

What services can I integrate using Stitch Incoming Webhooks?

With Stitch’s Incoming Webhooks integration, you have the ability to quickly and easily integrate with dozens of services that use webhook APIs. Some notable services include:

What do I need to use Stitch webhooks?

You need a Stitch account to use the Stitch webhooks integration.

In addition, the webhook API you want to use must meet the following requirements:

  • The data sent by the webhook API must come to Stitch in JSON format. This is currently the only format Stitch supports.
  • The payload (or delivery) of the data must come via a POST request.
  • The request body must be less than 4MB

You can determine if the webhook API you want to use meets the above criteria by checking out their webhook API documentation. If you’re not sure or the docs are unclear, please reach out to support.

Incoming Webhooks Setup

Do I have to provide a Primary Key?

Defining a Primary Key is optional. The Incremental Replication Method Stitch uses will depend on whether a Primary Key is defined when the integration is initially created, however:

  • If a Primary Key is provided, replication to webhooks data will take place via an upsert. This means that existing rows can be updated.
  • If a Primary Key is NOT provided, replication will be append-only. Additionally, a Primary Key field called _sdc_primary_key. will be automatically generated. This is because Stitch requires Primary Keys to replicate data and prevent duplication.

Can I change the Primary Key after I’ve defined it?

We don’t recommend this, but yes, you can. Stitch uses Primary Keys to correctly replicate your data and prevent duplication; changing the Primary Key after the fact may result in fields not being updated correctly.

How do I set up webhooks in [name] app?

For instructions on how to set up webhooks in your provider’s app, refer to their documentation and reach out to their support team if you get lost. Depending on the provider you’re using, the steps for implementing webhooks may differ.

However: you can find setup articles in our docs for a few of the most popular apps that the Stitch Incoming Webhooks integration is compatible with, such as:

Does the Incoming Webhooks integration support historical data?

By design, most webhook-based integrations don’t retain historical data, as data is sent in real-time.

If the service you’re integrating with offers replay functionality, however, you may be able to send historical data to your Incoming Webhooks integration.

Webhook Data & Schema

What’s this _sdc_primary_key column?

When the Primary Key isn’t defined during the setup process, Stitch will automatically generate a Primary Key column called _sdc_primary_key. This is because Stitch requires Primary Keys to replicate data and prevent duplication.

Where will my Incoming Webhook data be located in my data warehouse?

In v1 of the Stitch Incoming Webhooks integration, Stitch will create a single table - called data - in the webhook integration schema (this will be the name you enter in the Integration Schema field when you set up the integration) of your data warehouse.

What will the schema of the Incoming Webhooks table look like?

The schema of an Incoming Webhooks table will contain two “types” of columns: columns used by Stitch (prepended with _sdc) and the columns sent by the provider’s webhook API.

Aside from the Stitch columns, the schema of this table will depend entirely on the provider of the webhook API. For example: if the webhook API you integrate with only contains id, event, and value fields, these are the only fields that will be created in the data table.

Stitch does not augment Incoming Webhook data, nor does it have any control over the fields sent by the webhook provider.

Why does the data table contain so many NULLs?

There are two reasons for this: one is the general nature of webhook data, and the other is how the Incoming Webhooks integration is designed.

The Stitch Incoming Webhook integration is designed to create only one top-level table. This single table will contain all the data that Stitch receives from your webhook, which can include several types of records. For example: if you set up Mandrill using Incoming Webhooks, your data table may contain records for whitelist events, click events, bounce events, and so on.

While each record type may contain some similar attributes (id, created_at, etc.), it's likely that each record type will have its own set of attributes, which will only be populated for that record or other specific record types.

As such, some columns in some records will contain NULLs. Here's an example with a Mandrill message send event, a whitelist add event, and a click event:

| id | ts         | event | action | type      | ip          | url           |        
| 1  | 1481730892 | send  | NULL   | NULL      | NULL        | NULL          |
| 2  | NULL       | NULL  | add    | whitelist | NULL        | NULL          |
| 3  | 1481732465 | click | NULL   | NULL      | | |   

// record 1 is a message send event
// record 2 is a whitelist add event
// record 3 is a click event

Why is there more than one table? You said there'd only be one table.

That's true; we did. However: if you're using Redshift, Postgres, or Panoply as your data warehouse, you may see multiple tables in your Incoming Webhooks integration schema. These are subtables, which a result of Stitch deconstructing nested data structures so the data can be loaded into your data warehouse. If the provider you integrate with uses nested data structures, you'll see subtables.

To learn more about this Stitch feature and how to tie subtables together in your queries, click on the links in the above paragraph.


Can you add Incoming Webhook docs for [integration?]

Our Technical Documentation Manager loves getting feedback and suggestions for docs. If you’re looking for something specific, write into support! We can’t promise that every suggestion will result in a new set of docs, but suggestions are welcomed and encouraged.

Was this article helpful?
0 out of 0 found this helpful


Questions or suggestions? If something in our documentation is unclear, let us know in the comments!