Ringura
Sign in Book a demo

Integrations

Use the API, webhooks and apps

Create API tokens with the scopes you need, send signed webhooks to your own systems, read their deliveries, and install or register apps.

Last checked For: Administrators

Steps

  1. Know what is on the page

    API and webhooks is where you connect your own systems. API tokens let a system read and change your data through the public REST API. Webhooks send events, such as a resolved conversation or a call outcome, to an address you choose as they happen. Any tool that can call a REST API with a bearer token, or receive a signed HTTPS webhook, can be connected this way. The page is for administrators.

  2. Pass two-step verification first

    Creating a token needs two-step verification in the session you are using. If the page says Pass MFA in this session to create API tokens (Security page)., sign out and in again with your second step, or set it up first: see Turn on two-step verification.

  3. Create an API token

    Under API tokens, in New token, enter a Name, how long it is Valid for (days) (1 to 365, 90 by default) and the Requests per minute it may make (600 by default). Under Scopes, tick only what the system needs: the read scopes are ticked for you; add write scopes such as contacts:write or messages:write if it must change data. Choose Create token.

  4. Copy the token and use it

    The console shows: Copy this token now; it is not shown again: followed by the token. Store it in the system that will use it. It sends the token in the header Authorization: Bearer followed by the token, never in a URL. The OpenAPI document describes every operation and the scope it needs; the developer documentation (/developers/) explains paging, rate limits and retries. A request outside the token's scopes is refused.

  5. Revoke a token and limit its networks

    To stop a token, open Security and choose Revoke on its row; anything using it stops working. On the same page, Networks allowed to use API tokens (one CIDR block per line; empty allows all) restricts where tokens may be used from. See Roles, network limits and API tokens.

  6. Add a webhook endpoint

    Under Webhooks, in New endpoint, enter the URL (https) of your receiver and an optional Description. Under Event types, tick the events you want, or Every event in the catalogue. Choose Create endpoint. The console shows: Copy this signing secret now; it is not shown again: followed by the secret. Give it to your receiver.

  7. Check each delivery's signature

    Every delivery is signed: CC-Signature carries t (Unix seconds) and v1, the HMAC-SHA-256 of "t.body" under the endpoint's secret. Refuse a signature older than 5 minutes or one you have already seen, and dedupe on CC-Event-Id. Answer with a 2xx status when you have the event. Code samples are in the webhooks documentation (/developers/webhooks/).

  8. Read the deliveries

    On an endpoint, choose Deliveries. Each row shows the Event, its Status (Waiting to retry, Delivered or Dead letter), the Attempts and the Last result. Use Show to list one status. A delivery that is not answered with a 2xx is retried with growing waits, up to eight attempts, then becomes a Dead letter. Choose Replay to send a dead or delivered event again with a fresh signature.

  9. Rotate the secret or pause an endpoint

    Choose Rotate secret to get a new signing secret, shown once. The old secret also signs for 24 hours, so you can update your receiver without losing events. Disable stops deliveries to the endpoint; Enable starts them again. The Event catalogue at the bottom of the page lists every event with the fields it carries.

  10. Install an app

    Apps lists the apps in the Marketplace. Open What it may do to see an app's permissions, then use its install link, which asks you to allow access. Installed apps shows who installed each app and when it was last used. Uninstall ends its access at once and revokes every token of the app.

  11. Register your own app

    On App developer, under Register an app, enter the Name, Developer name, Redirect URIs and Client type, tick the Permissions the app may ask for, and optionally a Webhook URL with its Webhook events. Choose Register the app: the Client ID, and for a confidential app the Client secret, are shown once. The app installs in your organisation only until you choose Submit for listing.

Good to know

  • A system that wants events as they happen can keep a connection open instead of receiving webhooks: give a token the events:read scope, then open the WebSocket at /api/realtime with the token in the Authorization header, never in the address. It carries the same events as webhooks. Use ?after= with the last sequence number you saw to carry on after a disconnection, and ?types= to take only some events. Each token can hold 5 connections, and a revoked token loses its connection within 30 seconds.
  • Tokens made on the Security page get the read scopes only: they read your organisation's data and cannot change anything. Make tokens that write on API and webhooks.
  • A token stops working on its expiry date. Make a new one before then and replace it in your system.
  • A system that sends more requests per minute than its token allows is answered with status 429 and a Retry-After header saying how long to wait.
  • Internal notes are never sent to webhooks: only inbound and outbound messages are.
  • If Create endpoint says Choose at least one event type., tick at least one event or Every event in the catalogue.
  • While an installed app is uninstalled or disabled, its webhook receives nothing; events that happened meanwhile are not sent later.
  • API tokens, webhooks and apps are the feature API access and apps on Feature access. While it is off for you, API and webhooks, Apps and App developer are hidden.
  • To log calls and outcomes in a CRM without building anything, use a CRM connector: see Connect your CRM.

Still stuck?

Write to hello@ringura.com, or use the contact page, and say which guide you were following.

ContactHelp centre