Stage events
Tell Askivo when a customer reaches a stage in your own system, such as a booking made, a trial about to end or a first payment. Askivo sends the approved WhatsApp template you chose for that stage, or makes a task for your staff when you chose none.
It is one signed web request. Any system that can send one works: your own software, or an automation tool that can compute an HMAC, such as Make or n8n. Connections are part of the Growth and Enterprise plans and are created in the dashboard under WhatsApp, Automations.
The request
Send a POST to the address shown for your connection in the dashboard. It looks like https://askivo.ai/api/integrations/<id>/events.
{
"event": "stage.changed",
"account_id": "cust-8812",
"stage": "trial_ending",
"previous_stage": "first_invoice",
"at": "2026-11-20T05:07:00Z",
"whatsapp": "+60123456789",
"language": "en",
"fields": {
"first_name": "Aisyah",
"company_name": "Kedai Aisyah",
"trial_end": "2026-11-23"
},
"source": { "utm_source": "facebook", "utm_campaign": "nov" }
}| event | Required | Always "stage.changed". Anything else is acknowledged and ignored. |
| account_id | Required | Your own id for the customer, company or deal. Up to 100 characters. |
| stage | Required | The key of a stage you defined in the dashboard. |
| at | Required | When it happened, as an ISO 8601 time. Part of the duplicate check. |
| Optional | The person's number with country code, only if they agreed to WhatsApp contact. Leave it out or send null otherwise. | |
| previous_stage | Optional | The stage they were in before. Send the same value as stage to say: consent or the number arrived late, act on this stage now. |
| previous_whatsapp | Optional | Only on the one event after a person changes their number: the number you sent before. |
| previous_account_id | Optional | The id this customer was reported under before, for example a sign-up before an account existed. Askivo closes the follow-up filed under it. |
| language | Optional | The person's language, such as "en" or "ms". Defaults to "en". |
| fields | Optional | Values for template placeholders, by the keys you defined in the dashboard. Up to 20, each up to 200 characters. |
| source | Optional | Where the person came from: utm_source, utm_medium, utm_campaign, utm_content, utm_term. Shown to staff on the task. |
Fields Askivo does not know are ignored, so you can add your own without breaking anything.
Signing
Every request carries two headers. X-Askivo-Timestamp is the current time in Unix seconds. X-Askivo-Signature is v1=followed by the hex HMAC-SHA256 of the timestamp, a full stop and the request body, keyed with your connection's secret.
Sign the exact text you send. If your code builds the JSON once to sign it and again to send it, the two can differ by a space and the signature will not match. A request more than five minutes old or new is refused, so a captured request cannot be replayed later.
Check your code against this example before you send anything real:
secret test_secret_do_not_use
timestamp 1763600000
body {"event":"stage.changed","account_id":"cust-8812","stage":"trial_ending","at":"2026-11-20T05:07:00Z","whatsapp":null}
signed text 1763600000.{"event":"stage.changed", ... }
signature v1=014e26d4fae359d90a0de312682018a8e81ff7bfd8dbf67aaf7859875af00813JavaScript (Node.js)
import crypto from "node:crypto";
const body = JSON.stringify(event); // sign and send this exact text
const timestamp = String(Math.floor(Date.now() / 1000));
const signature =
"v1=" + crypto.createHmac("sha256", process.env.ASKIVO_SECRET).update(timestamp + "." + body).digest("hex");
await fetch(process.env.ASKIVO_EVENTS_URL, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Askivo-Timestamp": timestamp,
"X-Askivo-Signature": signature,
},
body,
});Python
import hashlib, hmac, json, os, time
import requests
body = json.dumps(event, separators=(",", ":")).encode() # sign and send these exact bytes
timestamp = str(int(time.time()))
digest = hmac.new(os.environ["ASKIVO_SECRET"].encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
requests.post(
os.environ["ASKIVO_EVENTS_URL"],
data=body,
headers={
"Content-Type": "application/json",
"X-Askivo-Timestamp": timestamp,
"X-Askivo-Signature": "v1=" + digest,
},
timeout=10,
)PHP
$body = json_encode($event); // sign and send this exact text
$timestamp = (string) time();
$signature = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $body, getenv('ASKIVO_SECRET'));
$ch = curl_init(getenv('ASKIVO_EVENTS_URL'));
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-Askivo-Timestamp: ' . $timestamp,
'X-Askivo-Signature: ' . $signature,
],
]);
curl_exec($ch);What comes back
A request Askivo accepted answers 200 with {"status": "ok", "outcome": "..."}.
| template_sent | The stage's approved template was sent to the person. |
| task_created | No template is set for the stage, or the send was refused: staff got a task, with the reason. |
| no_whatsapp_consent | The event had no number. The stage is kept; nobody is messaged. |
| unknown_stage | The stage is not one you defined. Nothing is done; it shows under Recent events. |
| channel_missing | The WhatsApp number the connection sends from is no longer connected. |
- 401: the signature did not match, or the request was older than five minutes.
- 404: the connection does not exist or is switched off.
- 413: the body is larger than 16 KB.
- 422: the body is not JSON, or a required field is missing.
Retries and duplicates
If a request fails or times out, send it again with a fresh timestamp and signature. Askivo treats two events with the same account_id, stage and at as one: the second answers {"status": "duplicate"} and does nothing, so retrying is always safe.
What Askivo does with an event
- The person becomes a contact on your WhatsApp number, tagged with your system's name.
- A stage with an approved template sends it, once per account per stage.
- A person gets at most one automatic message in any 20 hours, whatever the stages do.
- Nobody who opted out is messaged, and a promotion is skipped for anyone who pressed Stop promotions.
- When a send is refused or fails, your staff get a task that says why.
- A newer stage closes the task an older stage made, so staff see only the latest.
Consent is yours to collect
Send a WhatsApp number only for a person who agreed to be contacted on WhatsApp, for example with a tick box on your sign-up form. An event without a number is still useful: Askivo keeps the stage and messages nobody. Check numbers on your form too. A mistyped digit is the usual reason a first message is never delivered.
Make and n8n
n8n:build the body as text in a Code node, compute the signature in the same node with Node's crypto module as in the JavaScript example, then send that same text from an HTTP Request node with the body set to raw JSON and the two headers added.
Make: put the body text in a variable, compute the signature with the built-in sha256 function using your secret as the key and hex output, then send the variable as the raw body of an HTTP request with the two headers added.
In both, the text you sign and the text you send must be the same variable.
Try it first
In the dashboard, Send a test event posts an example with no WhatsApp number, so it messages nobody, and shows what came of it. Show an example request gives a signed request you can paste into a terminal. Recent events lists what arrived and what each one did.
Questions: hello@askivo.ai. Plans are on the pricing page.