Start an automation from your own system

This page is for whoever looks after your system — your developer, or the person who sets up your Zapier, Make or n8n. Everything they need is below.

Make the automation and copy its address

1. Go to AI Studio › Flows and press New automation.
2. Name it, choose WhatsApp or Instagram, and say whether it’s about something they did (an order, a booking, a payment) or a promotion.
3. Copy the Address, the Test address and the Secret. The secret is shown once — if it’s lost, press Make a new secret in the automation’s start.
4. Paste a sample of what your system will send, choose which field says who the customer is, and which fields become blanks in your messages. Press Use these fields.

The request

POST https://<the address you copied>
Content-Type: application/json
X-InsideDM-Signature: t=<unix seconds>,v1=<hex signature>
Idempotency-Key: <your own id for this event — optional, recommended>

• The body is one JSON object, at most 64 KB. Only the fields you chose are kept; everything else is dropped as it arrives.
• Who the customer is comes from the fields you chose: their mobile number (Indian numbers may leave out +91), email, Instagram username, WhatsApp user id (BSUID), or your own id for them. They’re tried in that order. A number we don’t know yet adds the customer (WhatsApp); your own id is remembered, so a later call can send only that.
• A field you marked as needed must be in every call, or the call is refused and says which.

The signature

The secret looks like whsec_ followed by 43 characters. The key is the 32 bytes those characters encode (base64url). Sign the timestamp, a dot, and the exact bytes you send:

v1 = hex( HMAC-SHA256( key, "<t>." + body ) )

Sign each request when you send it: a timestamp more than 5 minutes from our clock is refused. It’s the same scheme InsideDM uses to sign the webhooks we send you, so the same code works both ways.

Node.js:

import { createHmac } from "node:crypto";

const key = Buffer.from(process.env.INSIDEDM_SECRET.slice("whsec_".length), "base64url");
const body = JSON.stringify({ customer: { mobile: "+91 98765 01234", name: "Aditi Rao" }, order: { number: "A-1042" } });
const t = Math.floor(Date.now() / 1000);
const v1 = createHmac("sha256", key).update(`${t}.`).update(body).digest("hex");

await fetch(process.env.INSIDEDM_ADDRESS, {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-insidedm-signature": `t=${t},v1=${v1}`,
    "idempotency-key": "order-A-1042-shipped",
  },
  body,
});

Python:

import base64, hashlib, hmac, json, os, time, urllib.request

secret = os.environ["INSIDEDM_SECRET"][len("whsec_"):]
key = base64.urlsafe_b64decode(secret + "=")
body = json.dumps({"customer": {"mobile": "+91 98765 01234"}, "order": {"number": "A-1042"}}).encode()
t = str(int(time.time()))
v1 = hmac.new(key, t.encode() + b"." + body, hashlib.sha256).hexdigest()

request = urllib.request.Request(os.environ["INSIDEDM_ADDRESS"], data=body, method="POST", headers={
    "content-type": "application/json",
    "x-insidedm-signature": f"t={t},v1={v1}",
    "idempotency-key": "order-A-1042-shipped",
})
urllib.request.urlopen(request)

curl, from a terminal:

SECRET='whsec_…'
ADDRESS='https://…'
BODY='{"customer":{"mobile":"+91 98765 01234","name":"Aditi Rao"},"order":{"number":"A-1042"}}'
TS=$(date +%s)
KEY_HEX=$(printf '%s=' "${SECRET#whsec_}" | tr '_-' '/+' | base64 -d | xxd -p -c 256)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$KEY_HEX" | sed 's/^.*= //')
curl -sS -X POST "$ADDRESS" \
  -H 'content-type: application/json' \
  -H "x-insidedm-signature: t=$TS,v1=$SIG" \
  -H 'idempotency-key: order-A-1042-shipped' \
  --data-raw "$BODY"

Repeats are harmless

Send an Idempotency-Key — your own id for the event, 1 to 255 characters, no spaces. For 24 hours, a call with the same key gets the first call’s answer and its requestId, with Idempotent-Replayed: true, and starts nothing new. The same key with a different body is refused.

Without the header, an exact resend of the same signed request — a retry by your HTTP client — is still recognised as the first call. Two calls you sign separately are two events, so send a key whenever a retry could be re-signed.

What we answer

A 202 means we have the call, not that the customer got a message. What happened to each call — sent, waiting for their answer, or why it stopped — is in the automation’s Activity.

What the customer gets

• WhatsApp: the first message must be one of your approved messages — the customer may not have written to you for months. After they reply, your automation can send ordinary messages.
• Instagram: only a customer who messaged you in the last 24 hours can be reached. Anyone else is skipped, and the activity says so.
• A promotion only goes to customers who said yes to hearing from you.

Change the secret

Press Make a new secret in the automation’s start and give the new one to your system. The old secret keeps working until your system first signs with the new one, or for a day — whichever comes first — so nothing is dropped while you switch.