Back

This article describes how to create and configure custom API requests using Webhook.

In this article:

Table of Contents Placeholder

The Webhook connector offers powerful actions that allow you to configure highly-customized HTTP requests. The connector actions described in this article allow you to control all aspects of an HTTP request and offer powerful templating features designed to handle complex and dynamic data formats.

Prerequisites

Connector Actions

Action Name AudienceStream EventStream
Send Customized Data via HTTP Request (Advanced)
Send Batched Customized Data via HTTP Request (Advanced)

Configure Settings

If you have not done so already, go to the Connector Marketplace and add the Webhook connector. Read the Connector Overview article for general instructions on how to add a connector.

After adding the connector, configure the following settings:

  • Basic Authentication
    • Optional.
    • Username.
    • Enter username if API endpoint requires basic authentication.
  • Basic Authentication
    • Optional.
    • Password.
    • Enter password if API endpoint requires basic authentication.

Action Settings - Parameters and Options

Click Next or go to the Actions tab. This is where you configure connector actions.

This section describes how to set up parameters and options for the Customized Data and Batch Customized Data options.

Action - Send Customized Data via HTTP Request (Advanced)

Parameters

PARAMETER DESCRIPTION
Method
  • Required.
  • Select the request method.
URL
  • Required.
  • Provide the URL to submit the request to.
  • For template support, reference the template name to generate a URL from the template.
URL Parameters
  • Optional.
  • Provide parameters to append to the URL.
  • For template support, reference the template name to generate the parameter value from the template.
Headers
  • Optional.
  • Map HTTP header values to header names.
  • For template support, reference the template name to generate the header value from the template.
Cookies
  • Optional.
  • Map cookie values to cookie names.
  • Cookies are added as a single HTTP header value.
  • Example: Cookie: name1=value1; name2=value2
  • For template support, reference the template name to generate the cookie value from the template.
Body Content Type
  • Optional.
  • Select available type or provide a custom value.
  • All types are UTF-8 encoded and are added as a header.
  • Example: Content-Type: text/plain; charset=UTF-8
  • Content type is required if body data is provided
Body
  • Optional.
  • Provide data to construct message body.
  • Map values to names if body content type is "multipart/form-data" or "application/x-www-form-urlencoded", otherwise reference the template name and only select the Body option.
  • For template support, reference the template name to generate body data from the template.
Template Variables
  • Optional.
  • Provide template variables as data input for templates.
  • Name nested template variables with the dot notation.
  • Example: items.name
  • Nested template variables are typically built from data layer list attributes.
  • For additional information, see the Template Variables Guide.
Templates
  • Optional.
  • Provide templates to be referenced in either URL, URL Parameter, Header or Body Data.
  • Templates are injected by name with double curly braces into the supported fields.
  • Example: {{SomeTemplateName}}
  • When using OAuth, the template variable refers to the token returned by the auth request.
  • For additional information, see the Templates Guide.

Sending Access Tokens for Webhook OAuth2

Requests using Webhook OAuth2 must supply the access token in the request. The token generated by your OAuth2 connection is provided by the connector in a template variable named {{webhook_access_token}}, which is passed differently between each API. In the following example, it is expected in the Authorization: Bearer TOKEN_HERE "Authorization" header.

Use the following steps generate and map this header:

  1. Create a template named auth_template using the following example:
    Bearer {{webhook_access_token}}
  2. In the Headers section, map this template to Authorization.
    Webhook Custom and Batched.jpg
  3. Click Save.
  4. Save and Publish your changes.

Action - Send Batched Customized Data via HTTP Request (Advanced)

Parameters

Parameter Description
Method
  • Required.
  • Select request method.
URL
  • Required.
  • Provide URL to submit request to.
  • For template support, reference the template name to generate a URL from the template.
Body Content Type
  • Optional.
  • Select an available type or provide a custom value.
  • All types are UTF-8 encoded and are added as a header.
  • Example: Content-Type: text/plain; charset=UTF-8
  • Content type is required if body data is provided.
Body Data
  • Optional.
  • Provide data to construct the message body.
  • Map values to names if body content type is "multipart/form-data" or "application/x-www-form-urlencoded", otherwise reference the template name and only select the Body option.
  • For template support, reference the template name to generate body data from the template.
Suffix
  • Suffix
Prefix
  • Prefix
Joiner
  • Joiner
Record Count Maximum
  • Record count maximum
Time To Live (minutes)
  • Time to go live, in minutes
URL Parameters
  • Optional.
  • Provide parameters to append to the URL.
  • For template support, reference the template name to generate a parameter value from the template.
Headers
  • Optional.
  • Map HTTP header values to header names.
  • For template support, reference the template name to generate the header value from the template.
Cookies
  • Optional.
  • Map cookie values to cookie names.
  • Cookies are added as a single HTTP header value.
  • Example: Cookie: name1=value1; name2=value2
  • For template support, reference the template name to generate the cookie value from the template.
Template Variables
  • Optional.
  • Provide template variables as data input for templates.
  • For additional information, see the Template Variables Guide.
  • Name nested template variables with the dot notation, for example: items.name.
  • Nested template variables are typically built from data layer list attributes
Templates
  • Optional:.
  • Provide templates to be referenced in either the URL, URL Parameter, Header or Body Data.
  • For additional information, see the Templates Guide.
  • Templates are injected by name with double curly braces into supported fields.
  • Example: {{SomeTemplateName}}
  • When using OAuth, the template variable refers to the token returned by the auth request.

Validate the Action

Use one of the following methods to verify and troubleshoot the new actions:

  • Vendor User Interface
    If the vendor provides a web user interface that allows you to monitor changes, submit an action to the target vendor endpoint and verify it on the target endpoint.
  • PutsReq Bucket
    Send a test request to a sample PutsReq bucket URL. After configuring the Action fields, go to the following URL to examine the request received using the PutsReq user interface.
    https://putsreq.com/YOURBUCKETNAME/inspect
  • Trace
    Run the Trace tool and examine the action data. If you are using the template feature of this action, check the Template Variables JSON and Rendered Template: <template name>.

Sample Action Configuration

  1. Go to https://putsreq.com/ and click Create a PutsReq to create an endpoint for testing.PutsReq_YourPutsReqURL.jpg
  2. Copy the PutsReq URL.
  3. Go to the Actions settings for your Webhook connector.
  4. Scroll down to Method and click to expand.
  5. Select POST from the drop-down list.
  6. Scroll down to URL, click to expand, and paste the PutsReq URL into the URL parameter field.
    PutsReq_WebhookConnectorSettings_Method and URL.jpg
  7. Click Save.
  8. Save and Publish your changes.
  9. Run a Trace to verify that the action triggered as expected.

Vendor Use Cases

The following list provides examples of advanced configurations via Webhook that offer a foundation and overview of the possibilities when using custom requests.