Developers
The HeloFlow API and webhooks
Create leads, send WhatsApp templates and react to WhatsApp events from your own code — or connect Zapier, Make and Pabbly without writing any.
Scoped API keys
Each key gets only what it needs: leads:write, messages:send or conversations:read.
Signed webhooks
Every delivery carries an HMAC-SHA256 signature and a timestamp you can check.
Retries built in
Failed deliveries are retried with back-off before a webhook is switched off.
Getting started
- In HeloFlow, open Integrations → API keys and create a key. Tick only the scopes you need. The key starts with
rf_and is shown once. - Send it as a bearer token on every request. Requests and responses are JSON.
- Check it works with
GET /v1/me.
curl https://jbxzxhxszukdnpmmgvdm.supabase.co/functions/v1/wa-api/v1/me \
-H "Authorization: Bearer rf_your_key"
{"ok": true, "org_id": "…", "org_name": "Sunrise Interiors"}Base URL: https://jbxzxhxszukdnpmmgvdm.supabase.co/functions/v1/wa-api. Errors come back as HTTP 4xx with {"ok": false, "error": "<code>", "detail": …}. Phone numbers use international format with the country code.
Actions
Templates must already be approved by Meta in your workspace. Free-text messages only go through while the customer's 24-hour window is open; outside it, send a template.
- POST
/v1/leadsleads:writeCreate a lead, or update the open lead for that phone number.
{"phone": "+919876543210", "name": "Priya", "value": 25000, "tags": ["hot"]} - POST
/v1/messagesmessages:sendSend an approved template. Works any time.
{"to": "+919876543210", "template": {"name": "order_confirmation", "language": "en", "variables": ["Priya", "#1042"]}} - POST
/v1/messagesmessages:sendSend a text. Only inside the 24-hour window after the customer's last message.
{"to": "+919876543210", "text": "Hi Priya, your order is on its way."} - POST
/v1/leads/{lead_id}/notesleads:writeAdd a note to a lead.
{"text": "Called, wants a quote"} - POST
/v1/leads/{lead_id}/tagsleads:writeTag the lead's contact.
{"tag": "vip"} - POST
/v1/leads/{lead_id}/stageleads:writeMove a lead to a pipeline stage, by name or id.
{"stage": "Qualified"} - POST
/v1/eventsleads:writeRaise your own event, which can start a HeloFlow automation.
{"name": "quote_sent", "phone": "+919876543210", "data": {"amount": 25000}}
Lookups
- GET
/v1/meCheck a key: returns the workspace it belongs to.
- GET
/v1/contacts?phone=%2B919876543210leads:writeFind a contact and its open lead by phone number.
- GET
/v1/leads?phone=%2B919876543210leads:writeFind a lead by phone number.
- GET
/v1/conversations?limit=25conversations:readThe most recent conversations.
Webhooks
Add a URL under Integrations → Webhooks and pick the events. Each event is a POST with this body:
lead.createdA new lead, from any source: WhatsApp, a form, an ad, the API or an import.lead.stage_changedA lead moved to another pipeline stage.message.receivedA customer sent a WhatsApp message.form.submittedA customer completed a WhatsApp form.payment.paidA payment link sent in a chat was paid.tag.addedA tag was added to a contact.conversation.resolvedA conversation was marked resolved.
{
"id": "evt_1042",
"event": "lead.created",
"org_id": "…",
"created_at": "2026-10-29T10:00:00Z",
"data": {
"lead_id": "…",
"contact_id": "…",
"source": "fb_lead_ad",
"contact": { "phone": "+919876543210", "name": "Priya Sharma", "email": "priya@example.com", "tags": ["hot"] },
"lead": { "stage": "New enquiry", "value": 25000, "currency": "INR" }
}
}Check the signature
Each delivery has x-heloflow-timestamp and x-heloflow-signature: sha256=<hex>, the HMAC-SHA256 of <timestamp>.<raw body> with your webhook's secret. Reply with any 2xx within 10 seconds; anything else is retried.
import crypto from "node:crypto";
// secret: shown once when you create the webhook in HeloFlow.
export function isFromHeloFlow(rawBody, headers, secret) {
const ts = headers["x-heloflow-timestamp"];
const sig = headers["x-heloflow-signature"] ?? "";
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300; // reject replays older than 5 minutes
return fresh && sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}REST hooks
Platforms that manage their own subscriptions can subscribe with an API key instead. REST hook deliveries also include the lead and contact, so you get names and numbers without a second call.
- POST
/v1/hooksSubscribe a URL to an event. The key needs the event's scope (leads:write for lead, form, payment and tag events; conversations:read for messages and conversations).
{"event": "lead.created", "target_url": "https://example.com/heloflow"} - GET
/v1/hooksList this key's hooks.
- DELETE
/v1/hooks/{hook_id}Unsubscribe. A 410 Gone from your URL also removes the hook.
- GET
/v1/samples/{event}Recent events in the same shape as a delivery, for testing.
No-code tools
Zapier, Make and Pabbly Connect use the same API key: in HeloFlow, open Integrations and pick your tool for the step-by-step setup. See all integrations, or ask us about anything the API doesn't cover yet.
Start confirming conversations today
Connect your WhatsApp Business number, add your content and go live — 7-day free trial, no credit card.
Questions first? Read the FAQ
