8.3 Webex Developer Platform & APIs

8.3 Webex Developer Platform & APIs

Enterprise collaboration environments demand extensive integration with business applications, workflow automation tools, and administrative management platforms. The Cisco Webex Developer Platform provides programmable RESTful APIs, event-driven webhooks, and secure authentication models that allow engineers to automate user provisioning, control calling features, and build intelligent collaboration bots.

---

1. Webex Developer Platform Architecture & REST Standards

The Webex Developer Platform exposes a microservices-backed REST API architecture. All platform operations follow established Representational State Transfer (REST) conventions:

• Base Endpoint URL: https://webexapis.com/v1/{resource}
• Transport Security: Enforced strictly over Transport Layer Security (TLS 1.2 or 1.3) via HTTPS on TCP port 443.
• Data Interchange Format: Request payloads and response structures utilize standard JSON formatted with UTF-8 encoding (Content-Type: application/json; charset=utf-8).
• Standard HTTP Methods:
  • GET: Retrieve a resource representation or paginated resource collections.
  • POST: Create a new resource or execute a functional command.
  • PUT: Complete update or replacement of an existing resource object.
  • PATCH: Partial modification of specific resource attributes.
  • DELETE: Permanently remove a resource.

HTTP Response Status Codes

API Rate Limiting Mechanics

To safeguard cloud infrastructure against denial-of-service degradation, Webex enforces dynamic rate limiting using a token-bucket algorithm:

• HTTP 429 Response: When an application exceeds its allotted request volume, the Webex API server rejects subsequent calls with HTTP status 429 Too Many Requests.
• Retry-After Header: The response includes a mandatory HTTP header: Retry-After: <seconds> (e.g. Retry-After: 45), denoting the exact duration the application must pause before transmitting further requests.
• Exponential Backoff: Robust applications must parse the Retry-After header, queue pending requests, and implement exponential backoff with randomized jitter to prevent burst retries.

---

2. Core API Resource Endpoints

+-------------------------------------------------------------------------------------+
|                                 WEBEX REST API ENGINE                               |
|                               (https://webexapis.com/v1)                            |
+-------------------------------------------------------------------------------------+
         |                        |                         |                      |
         v                        v                         v                      v
    /v1/people                /v1/rooms                 /v1/messages         /v1/telephony
+------------------+     +------------------+      +------------------+   +------------------+
| User Lifecycle   |     | Spaces & Groups  |      | Rich Messaging   |   | Webex Calling    |
| - Provision User |     | - Create Spaces  |      | - Text / Markdown|   | - Call Queues    |
| - Assign License |     | - Add Members    |      | - File Uploads   |   | - Hunt Groups    |
| - Caller ID Info |     | - Moderation     |      | - Adaptive Cards |   | - Auto Attendant |
+------------------+     +------------------+      +------------------+   +------------------+

1. /people (User Management)

Manages the enterprise identity lifecycle, profile fields, and service licenses:

• GET /v1/people: Retrieves a paginated list of users; supports filtering by email, displayName, or orgId.
• POST /v1/people: Provisions a new user, allocating service licenses (e.g., Calling Professional, Meetings) and assigning calling extensions.
• GET /v1/people/{personId}: Retrieves granular profile information for a specific user UUID.
• GET /v1/people/me: Returns identity details and scopes for the currently authenticated bearer token.

2. /rooms (Spaces Management)

Administers collaborative workspaces (historically referred to as spaces or rooms):

• GET /v1/rooms: Lists spaces where the authenticated caller is an active participant.
• POST /v1/rooms: Creates a new direct or group collaboration space with a specified title.
• PUT /v1/rooms/{roomId}: Updates space metadata, renames spaces, or modifies team associations.
• /memberships: Complementary resource managing participant membership within spaces (GET, POST, DELETE).

3. /messages (Messaging & Interactive Cards)

Governs content transmission, document distribution, and workflow interactions:

• POST /v1/messages: Dispatches a message to a space (roomId) or direct recipient (toPersonEmail / toPersonId).
• Payload Parameters:
  • text: Plain-text representation displayed on notifications and legacy clients.
  • markdown: Formatted text supporting bolding, code blocks, lists, and hyperlinks.
  • files: Array of public HTTPS URLs containing files to attach to the space.
  • attachments: JSON payload embedding an Adaptive Card containing interactive input forms, buttons, and dropdown menus.
• /attachmentActions: Captures user button clicks and form submissions submitted through Adaptive Cards.

4. /telephony & /telephony/config (Webex Calling Provisioning)

Provides programmatic administration of enterprise call routing infrastructure:

• Automates provisioning of Webex Calling Locations, internal dial plans, and emergency routing numbers.
• Configures auto-attendants, hunt groups, call queues, call pickup groups, and shared call appearances.
• Manages individual user calling features: call forwarding rules, do-not-disturb, simultaneous ring, and unified voicemail settings.

---

3. Webex Authentication & Authorization Methods

Security is paramount when accessing collaboration APIs. Webex provides four distinct authentication and authorization models tailored to specific operational contexts.

Architectural Comparison of Authentication Models

1. Personal Access Tokens (PAT)

• Obtained directly from the Webex Developer Portal (developer.webex.com) when logged in with developer credentials.
• Valid strictly for 12 hours from issuance.
• Operational Boundary: Because PATs expire quickly and cannot be refreshed, they must never be hard-coded into production scripts, daemon processes, or scheduled cron tasks.

2. Bot Accounts

• Programmatic identities created on developer.webex.com that represent automated services or chatbots.
• Each bot receives a unique identity: <botname>@webex.bot, a distinct avatar, and a permanent API access token.
• Privacy & @Mention Rule: In 1:1 direct spaces, the bot automatically receives all messages. In multi-user group spaces, the bot receives message events only when explicitly @mentioned by a user. This architectural safeguard guarantees that bots cannot eavesdrop on private human conversations in group spaces.

3. OAuth 2.0 Integrations (3-Legged Authorization Code Flow)

Used when a third-party application needs to perform actions on behalf of a human user without learning or storing the user's password:

1. User Authorization Request: The application redirects the user's browser to the Webex authorization URL:

   GET https://webexapis.com/v1/authorize?client_id=C123...&response_type=code&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth&scope=spark%3Amessages_write%20spark%3Apeople_read&state=xyz123
   

2. Consent & Code Issuance: The user authenticates at Webex and consents to the requested scopes (e.g. spark:messages_write, spark:people_read). Webex redirects the user back to the application's redirect_uri with a temporary authorization code:

   GET https://app.example.com/oauth?code=AUTH_CODE_456&state=xyz123
   

3. Code Exchange for Access & Refresh Tokens: The application server makes a backend POST request to exchange the code:

   POST https://webexapis.com/v1/access_token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code&client_id=C123...&client_secret=SEC789...&code=AUTH_CODE_456&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth
   

4. Token Lifecycles:
   • Access Token: Valid for 14 days (1,209,600 seconds); passed in Authorization: Bearer <access_token> headers.
   • Refresh Token: Valid for 90 days (7,776,000 seconds).
   • Token Refresh: Before the 14-day access token lapses, the app sends grant_type=refresh_token to receive a fresh access token and a renewed 90-day refresh token, ensuring uninterrupted access without user re-authentication.

4. Service Apps (Machine-to-Machine Integration)

• Designed for enterprise backend systems (such as HR onboarding engines or archiving services) that require organization-wide access without human interaction.
• How it works:
  1. The developer registers the Service App on developer.webex.com, selects its scopes, and receives a client ID and client secret.
  2. A Full Administrator of the customer organization authorizes the app in Control Hub. Apps that request compliance scopes need a Full Admin who also holds the Compliance Officer role.
  3. The developer retrieves the organization's access token (about 14 days) and refresh token (about 90 days) from the app's Org Authorizations page or through the Applications API, using the client ID, client secret, and target organization ID, and refreshes it like an integration token.
  4. If the administrator later revokes the authorization in Control Hub, both tokens stop working.

---

4. Webhooks Architecture & Event-Driven Automation

Polling API endpoints (such as repeatedly calling GET /v1/messages every few seconds) is inefficient, consumes network bandwidth, and rapidly exhausts API rate limits (HTTP 429). Webex Webhooks provide an asynchronous, event-driven push architecture.

Webhook Registration

Applications register webhooks via POST https://webexapis.com/v1/webhooks:

{
  "name": "Support Space Alert Hook",
  "targetUrl": "https://api.enterprise.com/webhooks/webex",
  "resource": "messages",
  "event": "created",
  "filter": "roomId=Y2lzY29zcGFyazovL3VzL1JPT00vMGI5...",
  "secret": "SuperSecretSharedKey987!"
}

• targetUrl: Must be reachable from the internet; use HTTPS with a publicly trusted certificate so that the notifications are protected in transit.
• resource: The entity type to monitor (messages, memberships, rooms, telephony_calls, attachmentActions).
• event: The trigger event (created, updated, deleted, all).
• secret: A shared secret string used to cryptographically verify payload integrity and authenticity.

Webhook Event Delivery Payload & Content Decoupling

When an event occurs, Webex dispatches an HTTP POST request to the configured targetUrl:

{
  "id": "Y2lzY29zcGFyazovL3VzL1dFQkhPT0svZjQ...",
  "name": "Support Space Alert Hook",
  "targetUrl": "https://api.enterprise.com/webhooks/webex",
  "resource": "messages",
  "event": "created",
  "orgId": "Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8x...",
  "actorId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9hMT...",
  "data": {
    "id": "Y2lzY29zcGFyazovL3VzL01FU1NBR0UvYjI...",
    "roomId": "Y2lzY29zcGFyazovL3VzL1JPT00vMGI5...",
    "roomType": "group",
    "personId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9hMT...",
    "personEmail": "engineer@example.com",
    "created": "2026-10-06T15:30:00.000Z"
  }
}

Architectural Privacy Note: Notice that the webhook notification payload deliberately does not contain the message text or file contents. This prevents unauthorized exposure of message contents if webhook URLs are misconfigured. To read the message text, the application must take the data.id and issue an authenticated call (GET /v1/messages/{data.id}) using its authorized bot or user token.

Webhook Cryptographic Verification (X-Spark-Signature)

To prevent spoofing, tampering, and replay attacks, Webex signs every webhook payload:

1. Webex computes a Hash-based Message Authentication Code using SHA-1 (HMAC-SHA1) over the raw HTTP request body bytes, using the shared secret defined during webhook registration:

$\text{Signature} = \text{HMAC-SHA1}(\text{secret}, \text{raw\_body\_bytes})$

1. Webex includes the resulting hexadecimal signature string in the incoming HTTP request header:

   X-Spark-Signature: 3b7f2a9c0e41d5b8a6f39c27e1d0b4a85c6e9f12
   

2. Upon receiving the POST notification, the application server computes the identical HMAC-SHA1 digest on the raw unparsed request body using its stored shared secret.
3. The application executes a constant-time string comparison between its calculated digest and the X-Spark-Signature header value. If they match, the payload is authentic; if they differ, the server rejects the request with HTTP 401 or 403.