Setup Guide
5 minute read
This guide will help you set up a webhook destination in the RudderStack dashboard. It also lists the configuration settings required to correctly send data from the supported sources to your webhook destination.
Connection compatibility
| Destination Information | |||
|---|---|---|---|
| |||
Setup
In your RudderStack dashboard, add a source. Then, from the list of destinations, select Webhook.
Assign a name to uniquely identify your destination in the RudderStack dashboard and click Continue.
Connection settings
| Setting | Description | ||||||
|---|---|---|---|---|---|---|---|
| Webhook URL | Specify the endpoint where RudderStack sends the events. RudderStack supports both HTTP and HTTPS URLs.Note: For successful event delivery in case of an HTTPS URL, you must have a valid TLS certificate. | ||||||
| URL Method | Select the HTTP method of the request sent to the configured endpoint from the dropdown. By default, RudderStack uses the POST method to send the events. | ||||||
| Headers | Add custom headers for your events. RudderStack stringifies (for non-string data types) and adds these headers to the request made to your webhook. Note: RudderStack adds the below headers for the POST and PUT requests by default:
|
Configuration settings
Configure the below settings to receive your data correctly in your webhook destination.
| Setting | Description |
|---|---|
| Consent management settings | Configure the consent management settings for the specified source by choosing the Consent management provider from the dropdown and entering the relevant consent category IDs. See Consent Management in RudderStack for more information on this feature. |
Set non-string data types as headers
RudderStack supports defining non-string data types (like Boolean, object, array, etc.) as headers while setting up your webhook destination. RudderStack automatically stringifies these data types before setting the header.
For example, if you set the headers as shown:
In this case, RudderStack automatically stringifies and sets the below headers in the transformed payload before sending it to the specified webhook URL:
"headers": {
"key1": "null",
"key2": "{\"key1\":\"\"}",
"key3": "true",
}Add dynamic header to events
RudderStack provides a transformation template for cases where you need to dynamically change or add a header to the webhook, as shown:
export function transformEvent(event, metadata) {
event.header = {
Authorization: "Basic <credentials>", // Change headers and values
header_2: "<value>"
};
return event;
}The following snippet highlights a sample event payload with a dynamic header:
{
event: "Product Viewed",
type: "track",
properties: {
color: "blue",
number: 3,
newMember: true
},
header: {
"Authorization": "Bearer 3841718412jhcdskc"
}
}Add dynamic path to base URL
This feature is helpful in cases where you need to change the webhook endpoint depending on a certain condition.
RudderStack provides a transformation template for cases where you need to add a dynamic path to your base webhook URL.
For example, if the webhook URL configured in the RudderStack dashboard is https://www.example.com/, you can append a string /search?email=${email} to it depending on the email property present in your event:
export function transformEvent(event, metadata) {
const email = event.context?.traits?.email; // Change property
if (email) event.appendPath = `/search?email=${email}`; // Change property and appendPath
return event;
}In this case, the final webhook URL endpoint where RudderStack sends the event becomes https://www.example.com/search?email=${email}.
Transform events before sending to webhook
If you connect a transformation to your Webhook destination, RudderStack runs it on each event before sending it to the webhook.
Your function must return the final event you want to send to the webhook. RudderStack then maps that object to the HTTP request (JSON body, query string, and so on) based on the URL method and your connection settings.
Example: hash an email with SHA256
The following example replaces context.traits.email with a SHA256 hash, following the Hash PII pattern.
Input event
{
"anonymousId": "anon-dummyId",
"channel": "mobile",
"context": {
"traits": {
"age": 30,
"email": "test@example.com",
"firstName": "John",
"gender": "Male",
"lastName": "Doe"
}
},
"messageId": "d5112480-b9ff-4fb4-bb03-d8ebcad99b0a",
"type": "identify",
"userId": "userId16"
}Transformation
import { sha256 } from "@rs/hash/v1";
export function transformEvent(event, metadata) {
const email = event.context?.traits?.email;
if (email) event.context.traits.email = sha256(email);
return event;
}Output event (only the email trait is replaced with its hash)
{
"anonymousId": "anon-dummyId",
"channel": "mobile",
"context": {
"traits": {
"age": 30,
"email": "973dfe463ec85785f5f95af5ba3906eedb2d931c24e69824a89ea65dba4e813b",
"firstName": "John",
"gender": "Male",
"lastName": "Doe"
}
},
"messageId": "d5112480-b9ff-4fb4-bb03-d8ebcad99b0a",
"type": "identify",
"userId": "userId16"
}FAQ
How do I check for delivery failures while sending events to the webhook destination?
Log in to your RudderStack dashboard and go to the Live Events tab of your destination to check for any delivery failures. In case there are any, you can check the Error Response by clicking the event to get more details.
