Triggers

How it works

Create a trigger in the dashboard under Outbound → Triggers (next to Campaigns — everything that dials out lives together): pick the agent that makes the call and, optionally, the number it calls from. You get a unique URL. Every JSON event POSTed to that URL becomes an outbound call — the payload tells Qalyb who to dial and fills the agent's prompt variables so it opens the call knowing exactly why it's calling.

New triggers start in test mode: events run the whole pipeline (field mapping, validation, safety rails) and appear in the run log, but no call is placed. Arm the trigger once a test event looks right.

The event body

Tools that let you shape the payload (Zapier, Make, Zoho Flow, HubSpot Workflows, custom code) should send the canonical body:

POST https://api.qalyb.ai/triggers/hook/trg_a1b2c3d4...
Content-Type: application/json

{
  "to": "+971501234567",
  "variables": {
    "customer_name": "Layla",
    "topic": "your demo request"
  },
  "idempotency_key": "lead-4821"
}

• to — destination number. E.164 preferred; local formats are normalized when unambiguous.
• variables — optional map that fills the agent's {{variable}} prompt variables.
• idempotency_key — optional. Re-sends with the same key (CRM retries, double-fires) are deduplicated instead of calling twice. You can also send it as an Idempotency-Key header.

Tools with a fixed payload shape (Cal.com, Calendly, Typeform) work too: send one test event, then use the trigger's payload mapping to point the phone path and variable paths at the fields of the captured payload — e.g. payload.responses.phone.value.

Try it

curl -X POST https://api.qalyb.ai/triggers/hook/trg_a1b2c3d4... \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+971501234567",
    "variables": { "customer_name": "Layla" }
  }'

The endpoint acknowledges immediately and processes in the background:

{
  "received": true,
  "runId": "b3f1c9a0-..."
}

The outcome — call started, test logged, or rejected with a labeled reason — lands in the trigger's run log, linked to the call recording and transcript once the call runs.

Safety rails

• Dedupe window — the same number isn't called again within a configurable window (default 10 minutes), so sender retries never double-call a customer.
• Hourly cap — a hard limit on calls per rolling hour (default 20) contains a misconfigured workflow.
• Premium-rate destinations are always blocked, and events that fail validation are rejected with a reason you can read in the run log — they never silently dial.

Recipes

Zoho (Zoho Flow or CRM workflow webhook)

Create a flow on your event (e.g. Lead created), add a Webhook action with method POST and your trigger URL, and map the body:

{
  "to": "${Lead.Phone}",
  "variables": {
    "customer_name": "${Lead.Full_Name}",
    "company": "${Lead.Company}"
  },
  "idempotency_key": "${Lead.Lead_Id}"
}

HubSpot

In a Workflow, add the Send a webhook action (Operations Hub) pointed at your trigger URL, with to set to the contact's phone property. Without Operations Hub, route through Zapier or Make instead.

Cal.com & Calendly

Register the trigger URL as a webhook subscriber (Cal.com: Settings → Developer → Webhooks, event BOOKING_CREATED; Calendly: invitee.created). Their payloads arrive as-is — capture one test event and point the payload mapping at the attendee's phone field.

Zapier, Make, n8n

Use the generic webhook/HTTP action with method POST, the trigger URL, and the canonical JSON body. Any app those platforms support can now start a Qalyb call.

Securing the endpoint

The URL token is the credential — treat it like a secret and rotate it from the trigger page if it leaks. For senders that support signing, generate a signing secret on the trigger: events must then carry a valid signature or they are rejected.

x-qalyb-signature: t=1724900000,v1=5257a869e7...

signed_payload = "{t}.{raw_request_body}"
signature      = HMAC_SHA256(signing_secret, signed_payload)

The scheme is the same HMAC format Qalyb uses to sign outgoing webhooks, with a 5-minute replay tolerance.

Triggers vs. the calls API vs. campaigns

• Triggers — event-driven single calls from external tools. Scoped per-trigger URL, mapping, rails, and a run log. No API key needed in the external tool.
• Calls API — your backend places calls with an API key and full programmatic control.
• Campaigns — batch dialing a contact list with scheduling, retries, and campaign-level analytics.