Skip to content

Latest commit

 

History

History
215 lines (174 loc) · 7.38 KB

webhook-source.md

File metadata and controls

215 lines (174 loc) · 7.38 KB
Raw
description
Step-by-step guide to add a Webhook source in RudderStack.

Webhook Source

RudderStack lets you add any source that supports a webhook and use it to send events to your preferred destination.

When you create a webhook source in the RudderStack dashboard, you get a write key associated with it. Use this write key in a webhook endpoint in the format:

http://<DATA_PLANE_URL>/v1/webhook?writeKey=<SOURCE_WRITE_KEY>

You can then add this webhook URL to any source. RudderStack receives the data according to the settings made in the source, creates the payload, and routes it to your specified destination.

{% hint style="info" %} You must also add User Transformations ****to transform the event data into a destination-specific format. {% endhint %}

Adding a Webhook Source

This section details the steps involved in setting up a webhook source. As an example, we will configure Mailchimp ****as a source in RudderStack.

  • Assign a name to the source, and click on Next.
  • Your webhook source is now created, as shown below. Note the Webhook URL which will be added in the source platform.

  • Then, add a destination in RudderStack and connect it to this webhook source. In this example, we will configure Google Analytics as a destination, as shown:

{% hint style="info" %} Follow our guide on How to Add a Source and Destination in RudderStack for more details. {% endhint %}

  • Next, add the webhook URL to your desired source platform. Remember that you can configure webhook sources only for the source platforms that support webhooks. The following image shows the webhook URL added in Mailchimp:

{% hint style="info" %} Remember to add and test your webhook URL. {% endhint %}

  • When the users perform any of the actions configured in the source, the platform will send the generated events to the webhook URL.

In this example, Mailchimp sends the updates under What type of updates should we send? (seen in the image above) as user events to the webhook URL with the content type application/x-www-form-urlencoded.

{% hint style="info" %} The content type can vary in case of other webhook sources. {% endhint %}

  • RudderStack then takes the data, creates the payload and sends it to Google Analytics.

{% hint style="info" %} You must also add User Transformations ****to transform the payload into a destination-specific format before sending it to the destination. Refer to the Payload Creation and Transformation section for more details. {% endhint %}

Payload Creation and Transformation

This section details how RudderStack receives the data from the webhook source platform and creates the resulting payload.

Continuing with our Mailchimp example, suppose a customer subscribes to Mailchimp. Mailchimp then sends the following data to RudderStack:

type=subscribe&fired_at=2021-07-28+08%3A06%3A59&data%5Bid%5D=e2ff089583&data%5Bemail%5D=ruchira%40rudderlabs.com&data%5Bemail_type%5D=html&data%5Bip_opt%5D=115.187.35.152&data%5Bweb_id%5D=161912900&data%5Bmerges%5D%5BEMAIL%5D=name%40rudderlabs.com&data%5Bmerges%5D%5BFNAME%5D=Name&data%5Bmerges%5D%5BLNAME%5D=Surname&data%5Bmerges%5D%5BADDRESS%5D=&data%5Bmerges%5D%5BPHONE%5D=&data%5Bmerges%5D%5BBIRTHDAY%5D=&data%5Blist_id%5D=ec4689c266

RudderStack receives this data and creates the following payload:

[
  {
    "type": "track",
    "event": "webhook_source_event",
    "rudderId": "044448e2-a674-426c-ba61-8341262babcc",
    "messageId": "4379907d-689a-4e3a-a2f7-477e29a02299",
    "properties": {
      "type": [
        "subscribe"
      ],
      "data[id]": [
        "e2ff089583"
      ],
      "fired_at": [
        "2021-07-28 08:06:59"
      ],
      "data[email]": [
        "[[email protected]](mailto:[email protected])"
      ],
      "data[ip_opt]": [
        "115.187.35.152"
      ],
      "data[web_id]": [
        "161912900"
      ],
      "data[list_id]": [
        "ec4689c266"
      ],
      "data[email_type]": [
        "html"
      ],
      "data[merges][EMAIL]": [
        "[[email protected]](mailto:[email protected])"
      ],
      "data[merges][FNAME]": [
        "Name"
      ],
      "data[merges][LNAME]": [
        "Surname"
      ],
      "data[merges][PHONE]": [
        ""
      ],
      "data[merges][ADDRESS]": [
        ""
      ],
      "data[merges][BIRTHDAY]": [
        ""
      ]
    },
    "anonymousId": "d6597ba2-54db-4bd7-8769-86ac067b4178"
  }
]

You can then transform this payload according to the desired destination with the help of RudderStack's User Transformations feature.

A sample transformation is as shown below:

export function transformEvent(event) {
  const updatedEvent = event;
  const { properties } = event;
  
  if (properties) {
    updatedEvent.event = properties.type;
    updatedEvent.userId = properties["data[email]"];
    updatedEvent.properties.name = `${properties["data[merges][FNAME]"]} ${properties["data[merges][LNAME]"]}`;
    updatedEvent.properties.phone = properties["data[merges][PHONE]"];
  
    delete updatedEvent.properties["data[merges][PHONE]"];
    delete updatedEvent.properties["data[merges][FNAME]"];
    delete updatedEvent.properties["data[merges][LNAME]"];
  }
  
  return updatedEvent;
}

The transformed payload is as shown:

{
  type: 'track',
  event: [
    'subscribe'
  ],
  rudderId: '044448e2-a674-426c-ba61-8341262babcc',
  messageId: '4379907d-689a-4e3a-a2f7-477e29a02299',
  properties: {
    type: [
      'subscribe'
    ],
    'data[id]': [
      'e2ff089583'
    ],
    fired_at: [
      '2021-07-28 08:06:59'
    ],
    'data[email]': [
      '[email protected]'
    ],
    'data[ip_opt]': [
      '115.187.35.152'
    ],
    'data[web_id]': [
      '161912900'
    ],
    'data[list_id]': [
      'ec4689c266'
    ],
    'data[email_type]': [
      'html'
    ],
    'data[merges][EMAIL]': [
      '[email protected]'
    ],
    'data[merges][ADDRESS]': [
      ''
    ],
    'data[merges][BIRTHDAY]': [
      ''
    ],
    name: 'Name Surname',
    phone: [
      ''
    ]
  },
  anonymousId: 'd6597ba2-54db-4bd7-8769-86ac067b4178',
  userId: [
    '[email protected]'
  ]
}

RudderStack then sends this payload to your destination.

Contact Us

If you come across any issues while setting up and using webhook sources in RudderStack, feel free to contact us or start a conversation on our Slack channel.