Skip to content
HeloFlow

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

  1. 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.
  2. Send it as a bearer token on every request. Requests and responses are JSON.
  3. 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:write

    Create a lead, or update the open lead for that phone number.

    {"phone": "+919876543210", "name": "Priya", "value": 25000, "tags": ["hot"]}
  • POST/v1/messagesmessages:send

    Send an approved template. Works any time.

    {"to": "+919876543210", "template": {"name": "order_confirmation", "language": "en", "variables": ["Priya", "#1042"]}}
  • POST/v1/messagesmessages:send

    Send 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:write

    Add a note to a lead.

    {"text": "Called, wants a quote"}
  • POST/v1/leads/{lead_id}/tagsleads:write

    Tag the lead's contact.

    {"tag": "vip"}
  • POST/v1/leads/{lead_id}/stageleads:write

    Move a lead to a pipeline stage, by name or id.

    {"stage": "Qualified"}
  • POST/v1/eventsleads:write

    Raise your own event, which can start a HeloFlow automation.

    {"name": "quote_sent", "phone": "+919876543210", "data": {"amount": 25000}}

Lookups

  • GET/v1/me

    Check a key: returns the workspace it belongs to.

  • GET/v1/contacts?phone=%2B919876543210leads:write

    Find a contact and its open lead by phone number.

  • GET/v1/leads?phone=%2B919876543210leads:write

    Find a lead by phone number.

  • GET/v1/conversations?limit=25conversations:read

    The 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/hooks

    Subscribe 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/hooks

    List 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