Inbound Webhooks

Inbound webhooks can define a URL that can receive data and then translate the data into an "event" in the Kustomer platform. The Kustomer platform can then use the event with a Trigger to initiate a Workflow.

Inbound webhooks provide the main way for external data to enter the Kustomer platform.

There are three types of hooks:

Form hooks provide an unauthenticated path for posting data to Kustomer using an API endpoint
Webhooks require authentication
Email hooks receive data through email rather than an API endpoint

When a webhook is defined in an app, administrators who install the app will be able to see the hook URL displayed in the app directory after the app is installed.

You can learn more about inbound webhooks in the Kustomer Help Center.

Inbound webhooks format in the app definition

The hooks property takes an array of properties that define the following for each inbound webhook: a unique id for the event generated by the hook, event display name, event description, and hook type.

Inbound webhooks definition example

The following sample JSON app definition includes a hooks property definition that creates and configures the inbound webhook ecommstore.order.update in Kustomer.

{
  "app": "ecommstore",
  "version": "0.0.1",
  "title": "E-comm Store",
  "hooks": [{
    "eventName": "kustomer.app.ecommstore.order.update",
    "displayEventName": "Order Update Event",
    "description": "A hook triggered when an order is updated in Ecommerce Store",
    "type": "form"
  }]
}

Inbound webhooks property descriptions

The basic inbound webhooks definition properties and their descriptions are listed below:

eventName

Required. A globally unique id for the event created by the inbound webhook. If you want events to be routed to a workflow, the event name must begin with kustomer.app To ensure uniqueness, add <app name>. after kustomer.app or any other path that routes to a particular service.

Example: "eventName": "kustomer.app.ecommstore.order.update"

displayEventName

A display name for the event created by the inbound webhook. The display name appears in the UI when administrators manage webhooks. The name should describe the data coming into the hook.

Example: "displayEventName": "Order Update Event"

description

A longer description for the event created by the inbound webhook. The description appears in the UI for administrators who manage webhooks. The description should summarize the data coming into the hook and what the event means.

Example: "description": "A hook triggered when an order is updated in Ecommerce Store"

type

Defines the type of the inbound webhook created:

web
- A webhook. Requires an API key to be passed when making the request.
form
- A form hook. Uses a public API endpoint that does not require authentication.
email
- An email hook. Provides an email address that can receive emails and parse out JSON or JSON-LD directly from emails sent to the address.

Example: "type": "form"

You can learn more about inbound webhooks in the Kustomer Help Center.