API and outbound webhooks reference
Your instance's outbound API surface for operators is the webhook system configured under Settings → Webhooks: you register one or more endpoints, choose the events each should receive, and every matching event is POSTed to your URL as signed JSON. This page covers that configuration, plus how the instance's other API families are authenticated so you know which one you are dealing with when you see a request in your logs.
Two API families, two audiences
Arino One draws a firm line between endpoints the Arino portal calls and endpoints everything else calls.
| Prefix | Caller | Authentication |
|---|---|---|
/api/mgmt/* | The Arino platform portal only | Bearer token compared with a timing-safe check, plus a non-empty control header. Some endpoints additionally require a portal-granted scope (for example credentials:write, branding:manage). |
/api/public/* | Browsers, Infobip, your own systems, cron schedulers | Not behind a single shared key. Each route authenticates its own caller: a webhook/cron token in the query string, a session token, or nothing at all for genuinely public reads (site metadata, widget bootstrapping). |
You will never need to call /api/mgmt/* directly — it exists so the Arino portal can activate your instance, read its health, and manage entitlements. What you configure and consume as an operator is the outbound webhook layer under /api/public, described below.
Configuring an outbound webhook endpoint
- Go to Settings → Webhooks.
- Select New endpoint and provide a name, the destination URL, and an optional description.
- Tick the event types this endpoint should receive from the available list — there is no implicit "all events" subscription.
- Save. A signing secret is generated for the endpoint automatically; it is never displayed in the UI after creation, only referenced as "hidden (server-side only)".
- Toggle Enabled off at any time to pause deliveries without deleting the endpoint or losing its history.
Each endpoint's card shows its name, URL, event tags, and enabled state, with edit and delete actions and a button to rotate its secret.
Event types
The exact list of subscribable events is returned live from your instance (Settings → Webhooks shows the current set), because it grows as modules are enabled. At minimum you should expect message and conversation lifecycle events — for example an inbound message arriving, a conversation being created, or a delivery status changing — since these are the events most integrations (CRM sync, ticketing, data warehouses) need.
Signature verification
Every delivery is signed with HMAC-SHA256 and the endpoint's own secret, sent in the X-CBStudio-Signature header. To verify a delivery:
signature = HMAC_SHA256(secret, raw_request_body)Compare your computed signature against the header using a constant-time comparison. The most common integration mistake is hashing a re-parsed or re-serialised copy of the JSON body rather than the exact raw bytes received — most web frameworks parse the body automatically before your handler runs, which changes whitespace and key ordering and breaks the comparison even though the payload content is identical. Capture and hash the raw body before any JSON-parsing middleware touches it.
Retries and delivery visibility
Failed deliveries — non-2xx responses, timeouts, or connection errors — are retried automatically and recorded with a failed status, an attempt count, and, where available, the HTTP status code and error message returned. You can inspect this in two places:
- Settings → Webhooks, selecting an endpoint to see its delivery history, with a manual retry action on any failed delivery.
- Platform → Health, under the Webhook deliveries tab, which shows all endpoints' deliveries from the last 24 hours alongside the platform's other health signals — see platform health and diagnostics.
Because retries exist, your receiving endpoint should be idempotent: use the event's own identifier to detect and skip a delivery you have already processed, rather than assuming exactly-once delivery.
Secret rotation
Rotating a secret from an endpoint's card immediately invalidates the old one — every subsequent delivery is signed with the new secret, and your verification code must be updated with it before or at the moment you rotate, not after, to avoid rejecting genuine deliveries during the gap.
Design guidance for consumers
- Acknowledge fast. Return a 2xx status as soon as you have durably queued the event; do heavy processing asynchronously. A slow response is treated as a failure and triggers a retry even though the event was in fact received.
- Deduplicate on event ID, not on arrival order — retries can arrive out of order relative to your own processing.
- Fail closed on signature mismatch. Reject the request with a 401 rather than processing an unverified payload.
- Keep the endpoint list short and purposeful. One endpoint per downstream system with a tight event selection is easier to reason about and debug than a single endpoint subscribed to everything.
If deliveries stop arriving altogether, work through the dedicated diagnostic sequence in webhooks not arriving before assuming the platform failed to send the event — registration, endpoint health and TLS are the most common causes, in that order.
Frequently asked
Does every instance expose the same API?
Every Arino One instance runs the same route set, but the endpoints that matter to you as an operator are split by audience. Internal management endpoints are used by the Arino portal to activate the instance and read health; public endpoints under /api/public are what your own systems, Infobip, and cron schedulers call. There is no separate 'customer API key' family beyond the outbound webhook secret described here.
How do I authenticate an outbound webhook payload as genuinely from my instance?
Each webhook endpoint you create gets its own signing secret, generated when you save the endpoint. Every delivery includes an X-CBStudio-Signature header, an HMAC-SHA256 hash of the raw request body using that secret. Recompute the hash on the raw bytes you received — not a re-parsed or re-serialised copy — and compare it to the header before trusting the payload.
What happens if my endpoint is down when an event fires?
The delivery is recorded with a failed status and retried automatically. You can also see the failure immediately in the endpoint's delivery list under Settings → Webhooks, or in the platform-wide Webhook deliveries tab on the Platform health page, and trigger a manual retry from either place.
Can I subscribe one endpoint to only some event types?
Yes. When you create or edit an endpoint you tick the specific events it should receive from the available list — there is no all-events default, so an endpoint only receives what you have explicitly selected.
What is the difference between the webhook endpoints I configure and the Infobip webhook URL?
They are different things pointing in different directions. The Infobip webhook URL (configured in the Infobip portal, not in Arino One) is how Infobip pushes inbound messages and delivery reports into your instance. The outbound webhooks covered here are how your instance then pushes its own internal events — new conversation, message received, and so on — out to your own systems.
Do I need to rotate my webhook secret regularly?
There is no forced rotation schedule, but you should rotate immediately if a secret may have leaked — for example, committed to a public repository. Rotating from Settings → Webhooks invalidates the old secret immediately, so update your verification code with the new secret before or at the same moment you rotate, to avoid a gap in accepted deliveries.
Apply this to your own deployment
This guide describes decisions we make on live instances. Tell us your channels, systems and region and we will map it to an architecture outline, a provisioning plan and an indicative commercial model — usually within one business day.