See related
No related articles

Inbound webhooks

Last Update: Oct 2024 • Est. Read Time: 4 MIN
To check plan availability, see the pricing page.

Webhooks are a flexible way to sync your data between Kustomer and 3rd party applications. Kustomer offers both inbound webhooks, which are used to send events from other systems into Kustomer, as well as outbound webhooks for sending data from Kustomer into other systems.

This article will offer an overview of the various inbound webhook options available to users looking to send data into Kustomer.

Who can access this feature?
User typesAdmins can create new webhooks.


In this article

Overview

There are three types of hooks:

  • Form hooks
  • Webhooks
  • Email hooks

Each of these hooks gives you several options for triggering or activating workflows. They can be triggered by events that happen outside of Kustomer, or by events in Kustomer. Hooks and workflows give you the power and flexibility to have the most relevant and up-to-date data side-by-side with customer conversations. For example, you can use hooks to:

  • Create a custom object (KObject) in a customer's timeline when they place an order.
  • Update a customer’s email address when it’s added in your internal admin tool.
  • Create conversations in Kustomer when a customer fills out a web form.

Note: Hooks are the primary way to send generic data into Kustomer from other systems. If you are looking for how to send data from Kustomer to other systems, see our Workflows API.

Form hooks

Form hooks are unique URLs to which users can send data in an HTTP POST request. Currently, form hooks accept JSON and Form-Data content. Form hooks do not require any authentication and are best suited for use in public HTML forms, or anywhere the authenticity of the sender is not important.

Webhooks

Similar to form hooks, webhooks are also unique URLs that accept data in an HTTP POST Request. However, webhooks require authentication using an API Key that has the org.hooks role. Currently, webhooks accept JSON and Form-Data content. Webhooks are best suited for server-to-server communication where verifying the authenticity of the sender is important. In Kustomer, posting to a webhook requires a Kustomer API key with org.hook permission. For more information on creating and using API keys, see Authentication and API keys in our Developer Documentation.

Email hooks

Email hooks are unique email addresses that can be Bcc’d in order to trigger a workflow. Kustomer will parse JSON and JSON-LD syntax directly from the HTML markup in your email and make it available to you in a workflow. Email hooks are commonly used to update order and shipment details in Kustomer by adding the email hook address in the Bcc field of emails that are already being sent to customers.

Create a hook

You can create and review all existing hooks from the Kustomer Platform settings.

To create an inbound webhook:

  1. In Kustomer, go to Settings> Platform > Inbound Webhooks.
  2. Select Add Inbound Webhook.
  3. Fill out the name and description of the new webhook.

    Note: We always recommend that you use clear and illustrative names and descriptions as a best practice so that it's easy to know what function this webhook performs if another member of your team reviews it at a later date.

  4. Choose the desired type of webhook.
  5. Then, select Create to save the new webhook.

Find your hook address

Once you've created a hook, you can use it in API calls and workflows. You can find the hook address in the Inbound Webhooks settings.

To copy a hook's address:

  1. In Kustomer, go to Settings> Platform > Inbound Webhooks.
  2. Locate the desired hook and select Menu.
  3. Select Copy Hook Address from the drop-down menu that appears.

Use your hook in a workflow

When you edit a workflow using the workflow editor, you can reference it without having to know its address.

To add a hook to a new workflow:

  1. Go to SettingsPlatform > Workflows.
  2. Select Add Workflow, then create a new workflow from a blank state or import via JSON.
  3. In the Workflow editor, select the Choose Trigger step. For the Trigger App, select Hooks.
  4. All of the existing hooks you've created will be displayed in the Trigger Event drop-down. Select the hook you created, then fill in a descriptive name and description.
  5. Once you’ve configured your workflow to use a hook trigger, the next step is to configure an action. Select the + icon, then select Action.
  6. Based on the example above, we’ll want to create a message whenever the web form is submitted, so select Kustomer as the Action App, then select Message: Create as the Action Event.
  7. Continue filling out and setting up the workflow as desired.

Note: Be sure to Save and turn on the Workflow at the top of the screen.

To make it easier to complete your Workflow, we recommend testing your hook with a typical payload and then using that example to populate the rest of the Workflow. To understand the data available to you, use the Workflow logger to find your test event. Copy the output of the Workflow's "Step 1" in the logs, and paste it into the “Example Webhook Data” field in the right bar.

Once complete, you’ll be able to access your data automatically in the step output drop-down menus in all of the actions of your Workflow. Keep in mind that this data will not persist across sections, but will the debugger tool will remain accessible.

Debug your hook

As you work to leverage your new hook in a workflow, there may be times where you want to either test the connection to see how the data comes over or troubleshoot a recent set of data that did not ingest successfully. The debugger tool can help with seeing the data Kustomer receives first-hand and that can be used to understand how the system is understanding your data.

To access the debugger tool, go to Settings > Platform > Inbound Webhooks. From there, navigate to the webhook you wish to debug, select next to it, and turn on the Debug setting. From that point forward, the most recent 10 inbound interactions to that hook can be seen by selecting and going to View Debug Logs. This can be helpful as you are able to verify the format of your data and troubleshoot or build your workflow based on that information.

Related articles