REST API and webhooks

Connect Omni to your own systems. Use the REST API to read and change data, and webhooks to get notified the moment something happens.

API tokens

Where: API tokens (/app/api-tokens)

1. Click Create token and give it a name that says where it's used, for example "Website signup form".
2. Choose its permissions (scopes). Give each token only the access it needs.
3. Copy the token now. It's shown only once. If you lose it, create a new one.

Send the token as a Bearer token with every request:

GET /api/v1/me
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

Revoke a token at any time to cut off its access immediately. Never put a token in front-end code or share it in chat.

Scopes

Scope	Allows
contacts:read / contacts:write	Read, or create, update and delete contacts
conversations:read	Read conversations and their messages
messages:write	Send messages
campaigns:read / campaigns:write	Read campaigns and recipients, or create, launch and pause campaigns
automations:write	Trigger automations
ai:read / ai:write	Read chatbots and knowledge bases, or add documents and chat with a bot
analytics:read	Read conversation, message, campaign and AI-usage statistics
social:write	Create social posts
webhooks:write	Manage webhook endpoints

REST API

All endpoints live under /api/v1 on your Omni address and return JSON.

Area	Main endpoints
Account	GET /me, PATCH /me
Contacts	GET /contacts, POST /contacts, GET / PATCH / DELETE /contacts/{id}
Conversations	GET /conversations, GET /conversations/{id}/messages
Messages	POST /messages/send
Campaigns	GET /campaigns, POST /campaigns, GET / PATCH /campaigns/{id}, POST /campaigns/{id}/launch, POST /campaigns/{id}/pause, GET /campaigns/{id}/recipients
Automations	GET /automations, POST /automations/{id}/trigger
AI	GET /ai/chatbots, POST /ai/chatbots/{id}/chat, GET / POST /ai/knowledge-bases, POST /ai/knowledge-bases/{id}/documents
Analytics	GET /analytics/conversations, GET /analytics/messages, GET /analytics/ai-usage, GET /analytics/campaign/{id}/funnel

The full reference, with request and response fields for every endpoint, is inside the app under API docs (/app/api-docs).

Rate limit: 60 requests per minute per user. If you go over, the API answers 429 Too Many Requests; wait and retry.

Webhooks

Where: Webhooks (/app/webhooks)

Webhooks send an HTTPS POST to your server when something happens in your workspace.

Adding an endpoint

1. Click New endpoint and enter your server's HTTPS URL.
2. Leave the event list empty to receive every event, or select specific events.
3. Save. Omni creates a signing secret for the endpoint.

Events currently delivered:

Event	Sent when
message.received	A customer message arrives
contact.created	A new contact is added
campaign.completed	A campaign finishes sending
test.ping	You click Test on the endpoint

Request format

Each delivery is a JSON body with these headers:

Header	Value
X-Webhook-Event	The event name, for example message.received
X-Webhook-Signature	t=<unix timestamp>,v1=<signature>
Content-Type	application/json

Verifying the signature

Check every delivery before you trust it:

1. Read t and v1 from the X-Webhook-Signature header.
2. Build the string <t>.<raw request body>, using the raw body exactly as received, before any JSON parsing.
3. Compute an HMAC-SHA256 of that string with your signing secret, as lowercase hex.
4. Compare it to v1 using a constant-time comparison. Also reject deliveries whose t is more than a few minutes old, to block replayed requests.

[$t, $v1] = sscanf($_SERVER['HTTP_X_WEBHOOK_SIGNATURE'], 't=%d,v1=%s');
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $t . '.' . $body, $secret);
$valid = hash_equals($expected, $v1) && abs(time() - $t) < 300;

Responding and retries

Return any 2xx status within 10 seconds to confirm delivery. If your server returns an error or times out, Omni tries again with growing delays (about 1 minute, then 5 minutes, 1 hour and 1 day), up to 5 attempts in total. Each attempt is listed under Deliveries. Respond quickly and do slow work afterwards, and make your handler safe to run twice for the same event.

Managing endpoints

• Test: send a test.ping delivery.
• Deliveries: see every attempt, its status code and the response.
• Rotate secret: create a new signing secret, then update your server straight away.
• Edit or delete the endpoint.

For your security, Omni only delivers to public internet addresses. URLs that point to private or internal networks are blocked.

Related: Automations: triggering from other systems · Reports