Inbound webhooks

An inbound webhook is an address (URL) that your own system, such as a CRM, shop or booking tool, can post to. Each delivery can start any flow whose Webhook received trigger uses that endpoint. Every delivery must be signed with the endpoint's secret, so nobody else can start your flows.

This page is about posting into IconEngage to start a flow. To have IconEngage post events out to your system, see Event webhooks.

Create an inbound webhook

1. Go to Automation › Inbound webhooks.
2. Click Create an inbound webhook.
3. Enter a Name, so you can recognise it when choosing it in a trigger.
4. Enter a Signing secret: at least 32 characters (up to 256). Use a long random value and store the same value on your system. Click Show secret to check what you typed.
5. Click Create inbound webhook.

The secret is stored encrypted and never shown again. Afterwards you see only its last four characters.

You can also create one without leaving the flow builder: in a Webhook received trigger, click Create a new inbound webhook. The new endpoint is chosen for that trigger at once.

The list

From a row's actions you can:

• Replace signing secret: the URL stays the same. The new secret works from the moment you save it, and the old one stops at once with no overlap. Update your system at the same moment, or disable the endpoint first if it can't switch instantly.
• Disable: the endpoint refuses every delivery until you Enable it again.

How your system signs a delivery

The page shows these rules under How your system signs a delivery:

1. Send a POST with a JSON object as the body, at most 256 KB.
2. Set the X-IconEngage-Timestamp header to the current time in Unix seconds. Deliveries more than 5 minutes off are refused.
3. Set the X-IconEngage-Signature header to v1= followed by the hex HMAC-SHA256, using the signing secret, of the timestamp, a full stop, and the exact body bytes.
4. An answer of 202 means the delivery was received. 409 means this exact delivery was already received, and nothing runs twice.

For example, from a shell:

TS=$(date +%s)
BODY='{"customer":{"wa_id":"919876543210"},"order":{"id":"A-1001"}}'
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -X POST "$ENDPOINT_URL" \
  -H "Content-Type: application/json" \
  -H "X-IconEngage-Timestamp: $TS" \
  -H "X-IconEngage-Signature: v1=$SIG" \
  --data "$BODY"

A 202 only means the delivery was received. Whether a flow starts is decided afterwards, as described below.

Use it in a flow

1. In a flow's draft, add the Webhook received trigger.
2. Under Inbound endpoint, choose your endpoint. Disabled endpoints are marked "(disabled)".
3. Under Where the contact's WhatsApp number is, enter the path to the customer's WhatsApp number in your JSON, for example customer.wa_id. The number must include the country code; a leading +, spaces and dashes are ignored.
4. Under Copy from the delivery, click Add mapping for each value you want in the flow: a path (like order.id) and the variable to put it in. Declare the variables first under Variables. Up to 20 mappings.
5. Build the rest of the flow and publish it.

What happens to each delivery:

• The number belongs to one of your contacts: a run starts for that contact.
• The number is not one of your contacts: no run starts. It is counted on the version's page as Webhook named no contact of yours. The webhook does not create contacts.
• You left the path blank (or the path isn't in the delivery): the run starts with no contact, so no step can message anyone, but HTTP and webhook steps still work.

The delivery is only ever read as data. Because the run has no conversation yet, the first message step must have Send from chosen and is usually a template. See Flows and WhatsApp numbers.