Custom API & Webhooks
When the integration you need isn’t in the catalog, the answer is HTTP. Omniflow supports outbound webhooks for events, inbound webhooks for triggers, and a public REST API for anything else.
Outbound webhooks (Omniflow → you)
Subscribe to events; Omniflow POSTs JSON to your endpoint when they happen.
Available events
| Event | Triggered by |
|---|---|
conversation.created | A new conversation lands in the inbox. |
conversation.resolved | A conversation is marked resolved. |
ticket.created | A new ticket is opened. |
ticket.status_changed | A ticket changes status. |
scorecard.created | A QA grader scores a conversation. |
agent.published | An AI agent is published or republished. |
training_attempt.completed | A trainee finishes a practice call. |
automation.triggered | A routing rule fires. |
Configure
- Settings → Integrations → Webhooks → New endpoint.
- Paste your URL.
- Pick events to subscribe to.
- Optional: set a shared secret. Omniflow signs every request with
X-Omniflow-Signature.
Delivery semantics
- At-least-once. Retries on 5xx with exponential backoff up to 24 hours.
- Ordered per-resource. Events for the same conversation arrive in order.
- Signed. Verify
X-Omniflow-Signatureto confirm authenticity. - Replay. Replay any failed delivery from the Webhooks → Deliveries log.
# Verify a signature
echo -n "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" \
| awk '{print $2}' | xxd -r -p | base64Don’t trust the source IP for authentication — verify the signature. Source IPs change; signatures don’t lie.
Inbound webhooks (you → Omniflow)
Trigger Omniflow workflows from external events:
| Use case | How |
|---|---|
| External system marked an order shipped → tag the conversation | POST to a webhook URL, configure tag rule. |
| Vendor’s incident page paged → escalate all related tickets | POST + custom rule. |
| Form submission on your site → create a contact + assign | POST + create-contact rule. |
Configure
- Settings → Integrations → Inbound webhooks → New trigger.
- Pick the resource (
conversation,ticket,contact,custom event). - Define the JSON shape you’ll POST.
- Save and copy the URL — it’s signed and unique to your workspace.
Custom agent tools
If your system has APIs you want the AI agent to call directly, expose them as agent tools instead of webhooks. See Tools & Actions.
The trade-off:
| Use webhooks if… | Use agent tools if… |
|---|---|
| Async — fire-and-forget | Sync — agent waits for the response |
| Reacting to Omniflow events | Driving Omniflow behavior from the agent’s reasoning |
| One workflow trigger per event | Many possible calls per conversation |
Public REST API
The full API covers everything in the UI. Common starting points:
| Endpoint | Use |
|---|---|
POST /api/v1/conversations | Ingest external transcripts. |
GET /api/v1/conversations/{id}/trace | Pull a full trace for one conversation. |
POST /api/v1/contacts | Create or upsert a contact. |
POST /api/v1/tickets | Create a ticket. |
GET /api/v1/scorecards | Pull QA scores in bulk. |
See API Reference.
Authentication
API requests use a workspace API key:
Authorization: Bearer omf_live_xxxxxxxxxxxxxxManage keys under Settings → API Keys. Keys can be scoped to specific resource types and rate-limited per key.
Use a separate API key per integration — easier to rotate, easier to audit when something goes wrong.
Rate limits
| Tier | Default |
|---|---|
| Default | 60 requests / minute / key |
| Burstable | 120 / minute, 1000 / hour |
| Custom | Set per-key in Settings → API Keys |
Hitting the limit returns 429; the Retry-After header tells you how long to back off.
Open in Omniflow
Related
| If you want to… | Go to |
|---|---|
| Read the full API | API Reference |
| Use webhooks for telephony recording | Telephony |
| Build an agent tool from your API | Tools & Actions |